LeaderboardBack to leaderboard — loading return destination
Opening report…
Loading report overview
M
MCP server
server.example.com/mcp
Tools and resources for your MCP client, with a public quality report and detailed checks.
Protocol
MCP 2025-11-25
Server version
1.0.0
Website
server.example.com
Supports
Tools · Resources
Overall score
90 /100
How is this score calculated?
Server metadata
Loading server metadata
Reviewed90/100
Discoverability
Loading discoverability
Reviewed90/100
Protocol
Loading protocol
Reviewed90/100
Tools
Loading tools
Reviewed90/100
MCP Apps
Loading mcp apps
Reviewed90/100
Tool documentation quality
Loading tool documentation quality
Reviewed90/100
LeaderboardBack to leaderboard — loading return destination
H
HYPD AI for Paid Ads & Analytics
mcp.hypd.ai/mcp/claude
HYPD's read-only reporting for the user's connected ad platforms — Google Ads, Meta Ads, Google Analytics, Merchant Center, Search Console, Microsoft Ads, LinkedIn Ads — plus keyword/SERP research and landing-page audits
HYPD's read-only reporting for the user's connected ad platforms — Google Ads, Meta Ads, Google Analytics, Merchant Center, Search Console, Microsoft Ads, LinkedIn Ads — plus keyword/SERP research and landing-page audits
HYPD provides read-only access to the User's connected ad and analytics platforms — Google Ads, Meta Ads (+ public Ad Library), Google Analytics 4, Merchant Center, Search Console, Tag Manager, Microsoft Ads, LinkedIn Ads, TikTok Ads — plus SERP/keyword research and landing-page checks. HYPD never creates, edits or deletes anything in the User's accounts; every tool is a read. Call `init` at the start of a new conversation for the getting-started guide (connectable platforms, id formats, plan status). Key terms: an Account is one Google Ads customer account (10-digit id, no dashes). list_skills and load_skill return HYPD's marketing methodology guides — background reference for audits, performance reviews, and recommendations; hypd_show_prompt_library shows HYPD's ready-made prompts for the user to pick and run, and prompt_templates_get returns one by key. Guards agents most often miss: `google_ads_run_gaql` on change_event REQUIRES a change_date_time filter within the last 30 days AND a LIMIT — older change history does not exist; GA4 realtime reports cannot combine most dimensions with metrics; call LinkedIn tools one at a time, never in parallel. Report tool errors as errors — never invent data a tool did not return.
Discoverability
0 pass · 1 partial0 passed · 1 partial8/100
Client listings and public setup information.
mcp.json or server-card.json
Either mcp.json or an MCP Server Card declaring this endpoint passes.
All view resources are readable and use ui:// with a supported MCP Apps HTML MIME type
Tool invocation metadata present
5 tool(s) missing openai/toolInvocation metadata
How to fix: For tools that render a UI resource, add openai/toolInvocation with string fields invoking and invoked (present-tense labels shown while the tool runs and after it finishes, e.g. "Searching…" / "Searched").
How to fix: Use a ui:// URI and text/html;profile=mcp-app. For mcp-use v1, use widgetMetadata.metadata.widgetDescription; for v2, use the bound tool's view.description. The current description check reads _meta.ui.widgetDescription or _meta["openai/widgetDescription"] on resource contents or linked tools, not resource.description. Consequently, v2 view.description alone may leave this warning: report the checker compatibility gap instead of adding unsupported v1 fields or claiming the warning is fixed.
How to fix: For ChatGPT submission, set one exact HTTPS origin such as "https://app.example.com" on every view via _meta.ui.domain (or openai/widgetDomain). Paths are not valid and all views in one app must share the origin.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Returns HYPD's getting-started reference: supported platforms, account identifier formats, how the tool groups relate, and current plan/trial status. Use when setup context is needed or the user asks what HYPD can access. Takes no arguments and does not access ad platforms.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
Expand internal abbreviations and remove technical prefixes from the display title.
Description96/100
List HYPD's marketing methodology guides (skills), with a name and a one-line description for each. Skills are reference documents on topics such as Google Ads account review, Shopping feed diagnostics or Meta creative review. Use when the user asks which guides are available, or to find the name to pass to load_skill. Takes no arguments and reads nothing from any external platform.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Return the full text of one HYPD marketing methodology guide (skill) by name, from list_skills. A skill is reference material written by HYPD: definitions, checklists and analysis steps for a topic such as wasted-spend review or landing-page checks. Use it as background when the user asks for that type of analysis. The text can be shown to the user on request. Reads nothing from any external platform.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
skillName
The MCP skill name to load. Use list_skills to find valid names.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"skill"
],
"properties": {
"skill": {
"type": "object",
"required": [
"name",
"title",
"description",
"updatedAt",
"content"
],
"properties": {
"name": {
"type": "string",
"description": "The guide's id."
},
"title": {
"type": "string",
"description": "The guide's title."
},
"content": {
"type": "string",
"description": "The guide itself, in Markdown."
},
"updatedAt": {
"type": [
"string",
"null"
],
"description": "When the guide last changed (ISO 8601), if known."
},
"description": {
"type": "string",
"description": "What the guide covers."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "load_skill",
"title": "Load a Hypd analysis skill",
"description": "Return the full text of one HYPD marketing methodology guide (skill) by name, from list_skills. A skill is reference material written by HYPD: definitions, checklists and analysis steps for a topic such as wasted-spend review or landing-page checks. Use it as background when the user asks for that type of analysis. The text can be shown to the user on request. Reads nothing from any external platform.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"skillName"
],
"properties": {
"skillName": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The MCP skill name to load. Use list_skills to find valid names."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"skill"
],
"properties": {
"skill": {
"type": "object",
"required": [
"name",
"title",
"description",
"updatedAt",
"content"
],
"properties": {
"name": {
"type": "string",
"description": "The guide's id."
},
"title": {
"type": "string",
"description": "The guide's title."
},
"content": {
"type": "string",
"description": "The guide itself, in Markdown."
},
"updatedAt": {
"type": [
"string",
"null"
],
"description": "When the guide last changed (ISO 8601), if known."
},
"description": {
"type": "string",
"description": "What the guide covers."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Load a Hypd analysis skill",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
Expand internal abbreviations and remove technical prefixes from the display title.
Description94/100
List HYPD's library of saved prompt templates: pre-written analysis and reporting requests a user can run against their connected accounts, for example a weekly Google Ads performance summary or a Merchant Center disapproval report. Each entry has a key, title, category, platforms, tags and runsIn (which assistant the template was written for). Optionally filter by category, platform or a text query over titles and tags. Use when the user asks which templates or ready-made reports exist. Pass the chosen key to prompt_templates_get.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
category
Only prompts in this category.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platform
Only prompts for this ad platform.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Case-insensitive match against title and tags.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Returns one saved HYPD prompt template as user-viewable text, selected by key. It does not execute the template, access an ad platform, or change data. Use when the user names a prompt to run, or to fetch the prompt the user picked after hypd_show_prompt_library listed keys without its table. To browse or pick a prompt, use hypd_show_prompt_library instead.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
key
The prompt's key, exactly as returned by hypd_show_prompt_library.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List Google Ads Accounts available for this user in Hypd. Use googleAdsId as the stable account identifier. If nothing is returned, no Google Ads Account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
List Merchant Center Accounts available for this user in Hypd. Use merchantCenterId as the stable account identifier. If nothing is returned, no Merchant Center Account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
List products for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250.
The description explains the capability, when to use it, and what to expect.
Inputs25/100
1 of 3 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Not provided
Missing description. Explain what this value means and how to supply it.
pageToken
Not provided
Missing description. Explain what this value means and how to supply it.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
List raw Merchant Center Account Issues for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts. Read-only; issues are fetched live from Merchant Center and results are stateless.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
Get a raw Merchant Center product payload for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts and productName returned by merchant_center_list_products.
Describe the returned information so the agent knows whether it will answer the request.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Clear enough to supply this argument.
productName
Product name returned by merchant_center_list_products.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get a Merchant Center product",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema36/100
Describe the returned fields so an agent can interpret the result.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description74/100
Get raw Merchant Center product status for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts and productName returned by merchant_center_list_products.
Describe the returned information so the agent knows whether it will answer the request.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
productName
Product name returned by merchant_center_list_products.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the Merchant Center Accounts linked to a Google Ads Account. Use googleAdsId returned by google_ads_list_accounts. Returns one row per Merchant Center Account, tagged with state ("active" for live links, or the invitation status such as PENDING_APPROVAL / ACCEPTED / REJECTED / REVOKED / EXPIRED when no active link exists). A Google Ads Account can link to multiple Merchant Center Accounts. connectedInHypd indicates whether that Merchant Center Account is also connected in Hypd. Read-only; results are stateless.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
googleAdsId
The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. "4621877911". Dashed or spaced input like "462-187-7911" is accepted and normalized to digits. Use this value to choose which Account to inspect or query.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "List Google Ads → Merchant Center links",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema62/100
Describe the returned fields so an agent can interpret the result.
{
"name": "google_ads_list_merchant_center_links",
"title": "List Google Ads → Merchant Center links",
"description": "List the Merchant Center Accounts linked to a Google Ads Account. Use googleAdsId returned by google_ads_list_accounts. Returns one row per Merchant Center Account, tagged with state (\"active\" for live links, or the invitation status such as PENDING_APPROVAL / ACCEPTED / REJECTED / REVOKED / EXPIRED when no active link exists). A Google Ads Account can link to multiple Merchant Center Accounts. connectedInHypd indicates whether that Merchant Center Account is also connected in Hypd. Read-only; results are stateless.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId"
],
"properties": {
"googleAdsId": {
"type": "string",
"pattern": "^\\d(?:[ -]*\\d)*$",
"description": "The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. \"4621877911\". Dashed or spaced input like \"462-187-7911\" is accepted and normalized to digits. Use this value to choose which Account to inspect or query."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"links"
],
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"required": [
"merchantCenterId",
"state",
"connectedInHypd"
],
"properties": {
"state": {
"type": "string"
},
"connectedInHypd": {
"type": "boolean"
},
"merchantCenterId": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Google Ads → Merchant Center links",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the Google Ads Accounts linked to a Merchant Center Account. Use merchantCenterId returned by merchant_center_list_accounts. Returns every link tagged with state. A Merchant Center Account can link to many Google Ads Accounts. connectedInHypd indicates whether that Google Ads Account is also connected in Hypd. Read-only; results are stateless.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "List Merchant Center → Google Ads links",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema66/100
Describe the returned fields so an agent can interpret the result.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Get product performance (clicks, impressions, click-through rate, conversions, conversion value) for a Merchant Center Account from the Merchant Reports API. Use merchantCenterId returned by merchant_center_list_accounts. A startDate and endDate (YYYY-MM-DD) are required. Segment rows by up to 4 dimensions (offer_id, title, brand, category_l1-l3, date, week, marketing_method) and sort with orderBy/orderDirection — e.g. orderBy clicks DESC for top products, ASC for zero-click products. Numeric metrics are returned as strings. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account.
The description explains the capability, when to use it, and what to expect.
Inputs61/100
5 of 7 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Clear enough to supply this argument.
startDate
Start of the reporting date range (YYYY-MM-DD). Required.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
End of the reporting date range (YYYY-MM-DD). Required.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
segments
Array of 1-4 dimensions to segment metrics by: offer_id, title, brand, category_l1, category_l2, category_l3, date, week, or marketing_method.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
orderBy
Metric to sort by. DESC for top products, ASC for zero-click products.
Clear enough to supply this argument.
orderDirection
Not provided
Missing description. Explain what this value means and how to supply it.
limit
Not provided
Missing description. Explain what this value means and how to supply it.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Compare your product prices against Google Shopping benchmark prices (price vs benchmark_price per product) for a Merchant Center Account. Use merchantCenterId returned by merchant_center_list_accounts. Requires Market Insights to be enabled on the Merchant Center Account; fails with an error otherwise. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250. Prices are returned as micros strings.
The description explains the capability, when to use it, and what to expect.
Inputs33/100
1 of 3 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Clear enough to supply this argument.
pageSize
Not provided
Missing description. Explain what this value means and how to supply it.
pageToken
Not provided
Missing description. Explain what this value means and how to supply it.
{
"name": "merchant_center_get_price_competitiveness",
"title": "Get price competitiveness",
"description": "Compare your product prices against Google Shopping benchmark prices (price vs benchmark_price per product) for a Merchant Center Account. Use merchantCenterId returned by merchant_center_list_accounts. Requires Market Insights to be enabled on the Merchant Center Account; fails with an error otherwise. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250. Prices are returned as micros strings.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"merchantCenterId"
],
"properties": {
"pageSize": {
"type": "integer",
"default": 50,
"maximum": 250,
"minimum": 1
},
"pageToken": {
"type": "string",
"minLength": 1
},
"merchantCenterId": {
"type": "string",
"minLength": 1,
"description": "Merchant Center ID returned by merchant_center_list_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"merchantCenterId",
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"nextPageToken": {
"type": [
"string",
"null"
]
},
"merchantCenterId": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get price competitiveness",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Get Shopping competitive visibility for a Merchant Center Account: view "competitors" lists businesses with similar impressions (rank, page overlap rate, higher position rate, relative visibility), "top_merchants" lists the top-ranked merchants, "benchmark" compares your impression trend against the category average over time. Use merchantCenterId returned by merchant_center_list_accounts. Requires startDate/endDate (YYYY-MM-DD), reportCategoryId (numeric Google product category id) and reportCountryCode (2-letter, e.g. US); trafficSource filters by ORGANIC, ADS, or ALL (default). Requires Market Insights to be enabled on the Merchant Center Account; fails with an error otherwise. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account.
The description explains the capability, when to use it, and what to expect.
Inputs56/100
6 of 8 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Clear enough to supply this argument.
view
competitors: similar businesses; top_merchants: top-ranked merchants; benchmark: your visibility trend vs category average.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
startDate
Start of the reporting date range (YYYY-MM-DD). Required.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
End of the reporting date range (YYYY-MM-DD). Required.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
reportCategoryId
Numeric Google product category id to report on.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
reportCountryCode
Two-letter country code, e.g. US.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
trafficSource
Not provided
Missing description. Explain what this value means and how to supply it.
limit
Not provided
Missing description. Explain what this value means and how to supply it.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List products that are disapproved or not eligible to serve (aggregated_reporting_context_status NOT_ELIGIBLE_OR_DISAPPROVED) for a Merchant Center Account, including per-product item issues with reasons. Use merchantCenterId returned by merchant_center_list_accounts. To inspect one product in depth, follow up with merchant_center_get_product_status using the product name from merchant_center_list_products — never construct product names by hand. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250.
The description explains the capability, when to use it, and what to expect.
Inputs25/100
1 of 3 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Not provided
Missing description. Explain what this value means and how to supply it.
pageToken
Not provided
Missing description. Explain what this value means and how to supply it.
{
"name": "merchant_center_list_disapproved_products",
"title": "List disapproved products",
"description": "List products that are disapproved or not eligible to serve (aggregated_reporting_context_status NOT_ELIGIBLE_OR_DISAPPROVED) for a Merchant Center Account, including per-product item issues with reasons. Use merchantCenterId returned by merchant_center_list_accounts. To inspect one product in depth, follow up with merchant_center_get_product_status using the product name from merchant_center_list_products — never construct product names by hand. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"merchantCenterId"
],
"properties": {
"pageSize": {
"type": "integer",
"default": 50,
"maximum": 250,
"minimum": 1
},
"pageToken": {
"type": "string",
"minLength": 1
},
"merchantCenterId": {
"type": "string",
"minLength": 1,
"description": "Merchant Center ID returned by merchant_center_list_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"merchantCenterId",
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"nextPageToken": {
"type": [
"string",
"null"
]
},
"merchantCenterId": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "List disapproved products",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Summarize product issues across the whole catalog of a Merchant Center Account: counts of products by approval status plus item issues aggregated by code and severity with sample offer ids. Use merchantCenterId returned by merchant_center_list_accounts. Scans up to 5000 products; if truncated is true the catalog is larger and counts are partial. Use merchant_center_list_disapproved_products to enumerate the affected products. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
merchantCenterId
Merchant Center ID returned by merchant_center_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Standard performance for an Account, Campaigns, Ads, Keywords, Search Terms or Bidding Strategies, with fixed columns. Choose reportType: customer, campaign, ad_group_ad, keyword, search_term, dsa_search_term or bidding_strategy. Rows total the date window and sort by cost. Use dateRange (default LAST_30_DAYS) or startDate + endDate together. limit defaults to 250, max 10000; truncated means more rows existed. additionalMetrics adds valid metrics.* fields; Google rejects unknown names. Rows use dotted GAQL names and raw Google units: cost_micros, average_cpc and cost_per_conversion are micros (divide by 1000000 for Account currency); conversions_value is already in currency. Use googleAdsId from google_ads_list_accounts. Use google_ads_run_gaql for custom filters, segmentation or other resources.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
googleAdsId
The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. "4621877911". Dashed or spaced input like "462-187-7911" is accepted and normalized to digits. Use this value to choose which Account to inspect or query.
Clear enough to supply this argument.
reportType
Which standard report to run. Each returns a complete, fixed column set for its level: customer (whole Account), campaign, ad_group_ad (individual Ads), keyword, search_term, dsa_search_term (Dynamic Search Ads search terms), bidding_strategy.
Clear enough to supply this argument.
dateRange
The reporting window, as one of Google's own presets. Ignored when startDate and endDate are given.
Clear enough to supply this argument.
startDate
Start of an explicit window, YYYY-MM-DD. Must be given together with endDate, and overrides dateRange.
Clear enough to supply this argument.
endDate
End of an explicit window, YYYY-MM-DD, inclusive. Must be given together with startDate.
Clear enough to supply this argument.
limit
Maximum rows to return, highest cost first. The response sets truncated when more rows existed.
Clear enough to supply this argument.
additionalMetrics
Extra metric columns to add to the report, e.g. ["metrics.ctr", "metrics.average_cpc"]. Each must be a real Google Ads metric field starting with "metrics." and Google rejects names it does not recognize. The report ignores columns it already includes rather than duplicating them.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"reportType",
"result",
"rowCount",
"truncated"
],
"properties": {
"result": {
"type": "object",
"required": [
"columns",
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Rows keyed by GAQL field name, in Google's own units. Money comes back in micros, a millionth of the Account's currency. Divide metrics.cost_micros, metrics.average_cpc and metrics.cost_per_conversion by 1,000,000 before showing a price.",
"additionalProperties": false
},
"endDate": {
"type": "string"
},
"repairs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes Hypd made to the query behind this report. Expect this to be absent, because the report builds its own query. Anything here means Hypd rewrote that query and the rows may not match the report definition."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"dateRange": {
"type": "string"
},
"startDate": {
"type": "string"
},
"truncated": {
"type": "boolean",
"description": "True when the Account had more rows than limit returned. Raise limit to see the rest."
},
"reportType": {
"enum": [
"customer",
"campaign",
"ad_group_ad",
"keyword",
"search_term",
"dsa_search_term",
"bidding_strategy"
],
"type": "string"
},
"googleAdsId": {
"type": "string"
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_ads_get_report",
"title": "Get Google Ads performance report",
"description": "Standard performance for an Account, Campaigns, Ads, Keywords, Search Terms or Bidding Strategies, with fixed columns. Choose reportType: customer, campaign, ad_group_ad, keyword, search_term, dsa_search_term or bidding_strategy. Rows total the date window and sort by cost. Use dateRange (default LAST_30_DAYS) or startDate + endDate together. limit defaults to 250, max 10000; truncated means more rows existed. additionalMetrics adds valid metrics.* fields; Google rejects unknown names. Rows use dotted GAQL names and raw Google units: cost_micros, average_cpc and cost_per_conversion are micros (divide by 1000000 for Account currency); conversions_value is already in currency. Use googleAdsId from google_ads_list_accounts. Use google_ads_run_gaql for custom filters, segmentation or other resources.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"reportType"
],
"properties": {
"limit": {
"type": "integer",
"default": 250,
"maximum": 10000,
"minimum": 1,
"description": "Maximum rows to return, highest cost first. The response sets truncated when more rows existed."
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "End of an explicit window, YYYY-MM-DD, inclusive. Must be given together with startDate."
},
"dateRange": {
"enum": [
"TODAY",
"YESTERDAY",
"LAST_7_DAYS",
"LAST_BUSINESS_WEEK",
"THIS_MONTH",
"LAST_MONTH",
"LAST_14_DAYS",
"LAST_30_DAYS",
"THIS_WEEK_SUN_TODAY",
"THIS_WEEK_MON_TODAY",
"LAST_WEEK_SUN_SAT",
"LAST_WEEK_MON_SUN"
],
"type": "string",
"default": "LAST_30_DAYS",
"description": "The reporting window, as one of Google's own presets. Ignored when startDate and endDate are given."
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Start of an explicit window, YYYY-MM-DD. Must be given together with endDate, and overrides dateRange."
},
"reportType": {
"enum": [
"customer",
"campaign",
"ad_group_ad",
"keyword",
"search_term",
"dsa_search_term",
"bidding_strategy"
],
"type": "string",
"description": "Which standard report to run. Each returns a complete, fixed column set for its level: customer (whole Account), campaign, ad_group_ad (individual Ads), keyword, search_term, dsa_search_term (Dynamic Search Ads search terms), bidding_strategy."
},
"googleAdsId": {
"type": "string",
"pattern": "^\\d(?:[ -]*\\d)*$",
"description": "The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. \"4621877911\". Dashed or spaced input like \"462-187-7911\" is accepted and normalized to digits. Use this value to choose which Account to inspect or query."
},
"additionalMetrics": {
"type": "array",
"items": {
"type": "string",
"pattern": "^metrics\\.[a-z0-9_]+$"
},
"maxItems": 20,
"description": "Extra metric columns to add to the report, e.g. [\"metrics.ctr\", \"metrics.average_cpc\"]. Each must be a real Google Ads metric field starting with \"metrics.\" and Google rejects names it does not recognize. The report ignores columns it already includes rather than duplicating them."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"reportType",
"result",
"rowCount",
"truncated"
],
"properties": {
"result": {
"type": "object",
"required": [
"columns",
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Rows keyed by GAQL field name, in Google's own units. Money comes back in micros, a millionth of the Account's currency. Divide metrics.cost_micros, metrics.average_cpc and metrics.cost_per_conversion by 1,000,000 before showing a price.",
"additionalProperties": false
},
"endDate": {
"type": "string"
},
"repairs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes Hypd made to the query behind this report. Expect this to be absent, because the report builds its own query. Anything here means Hypd rewrote that query and the rows may not match the report definition."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"dateRange": {
"type": "string"
},
"startDate": {
"type": "string"
},
"truncated": {
"type": "boolean",
"description": "True when the Account had more rows than limit returned. Raise limit to see the rest."
},
"reportType": {
"enum": [
"customer",
"campaign",
"ad_group_ad",
"keyword",
"search_term",
"dsa_search_term",
"bidding_strategy"
],
"type": "string"
},
"googleAdsId": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Google Ads performance report",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description72/100
Run a GAQL query for a Google Ads Account available in Hypd. Use googleAdsId returned by google_ads_list_accounts.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Explain the meaning of this value, not just its name.
googleAdsId
The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. "4621877911". Dashed or spaced input like "462-187-7911" is accepted and normalized to digits. Use this value to choose which Account to inspect or query.
Clear enough to supply this argument.
gaqlQuery
The Google Ads Query Language (GAQL) query to run for this Account.
Explain the meaning of this value, not just its name.
queryIntent
A natural language description of what this query is intended to measure and under which conditions — e.g. 'performance of active campaigns last 7 days'.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"result",
"truncated"
],
"properties": {
"result": {
"type": "object",
"required": [
"columns",
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"repairs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes Hypd made to your query that affect the result you are reading. Three kinds: segmenting fields added to SELECT, which Google requires whenever you filter on one and which change the granularity of the rows; a change_event start date moved forward into the 30 days Google serves; and a LIMIT added to a change_event or change_status query that had none, which caps the result at 10000 rows. Absent when the result matches the query you sent; corrections that do not change the result, such as field renames, are not listed."
},
"truncated": {
"type": "boolean",
"description": "True when only the first rows came back: a query without a LIMIT returns at most 10000 rows, and any result stops at about 1 MB of rows. Totals over these rows are not the Account's totals."
},
"googleAdsId": {
"type": "string"
},
"truncationNote": {
"type": "string",
"description": "Present when truncated: how many rows came back, and how to narrow the query."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_ads_run_gaql",
"title": "Run Google Ads GAQL query",
"description": "Run a GAQL query for a Google Ads Account available in Hypd. Use googleAdsId returned by google_ads_list_accounts.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"gaqlQuery"
],
"properties": {
"gaqlQuery": {
"type": "string",
"minLength": 1,
"description": "The Google Ads Query Language (GAQL) query to run for this Account."
},
"googleAdsId": {
"type": "string",
"pattern": "^\\d(?:[ -]*\\d)*$",
"description": "The Google Ads Account ID returned by google_ads_list_accounts: the numeric customer id as a digit string, e.g. \"4621877911\". Dashed or spaced input like \"462-187-7911\" is accepted and normalized to digits. Use this value to choose which Account to inspect or query."
},
"queryIntent": {
"type": "string",
"description": "A natural language description of what this query is intended to measure and under which conditions — e.g. 'performance of active campaigns last 7 days'."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"googleAdsId",
"result",
"truncated"
],
"properties": {
"result": {
"type": "object",
"required": [
"columns",
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"repairs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes Hypd made to your query that affect the result you are reading. Three kinds: segmenting fields added to SELECT, which Google requires whenever you filter on one and which change the granularity of the rows; a change_event start date moved forward into the 30 days Google serves; and a LIMIT added to a change_event or change_status query that had none, which caps the result at 10000 rows. Absent when the result matches the query you sent; corrections that do not change the result, such as field renames, are not listed."
},
"truncated": {
"type": "boolean",
"description": "True when only the first rows came back: a query without a LIMIT returns at most 10000 rows, and any result stops at about 1 MB of rows. Totals over these rows are not the Account's totals."
},
"googleAdsId": {
"type": "string"
},
"truncationNote": {
"type": "string",
"description": "Present when truncated: how many rows came back, and how to narrow the query."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Run Google Ads GAQL query",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Find ideas from 1-20 seed keywords, with search volumes, competition and bid metrics. Specify target-market location and language; omitted values use provider defaults, not Account-derived targeting (Google backend defaults to United States/English). Ideas come from Google Keyword Planner when the user has a usable Google Ads Account and from DataForSEO otherwise; either way they are market estimates, not that Account's campaign performance. Fresh results are stored for 24 hours. For paging/re-sorting, pass resultId plus page/pageSize/sortBy and omit keywords/location/language; paging does not fetch fresh provider data. Re-run the fresh lookup after expiry.
The description explains the capability, when to use it, and what to expect.
Inputs89/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keywords
1-20 seed keywords to find related keyword ideas for. Examples: ["running shoes", "nike running", "marathon training"]
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
Target-market language for keyword research, e.g. "English" or "German". No Account-derived default; omit when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
Target-market country for keyword research, e.g. "United States" or "Germany". No Account-derived default; omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Clear enough to supply this argument.
resultId
Result ID returned by a previous research_find_keywords call. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
sortBy
Sort related keyword ideas by relevance, search volume, competition, or bid metric. With resultId, sorts stored rows before paging.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "research_find_keywords",
"title": "Find keyword ideas",
"description": "Find ideas from 1-20 seed keywords, with search volumes, competition and bid metrics. Specify target-market location and language; omitted values use provider defaults, not Account-derived targeting (Google backend defaults to United States/English). Ideas come from Google Keyword Planner when the user has a usable Google Ads Account and from DataForSEO otherwise; either way they are market estimates, not that Account's campaign performance. Fresh results are stored for 24 hours. For paging/re-sorting, pass resultId plus page/pageSize/sortBy and omit keywords/location/language; paging does not fetch fresh provider data. Re-run the fresh lookup after expiry.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"sortBy": {
"enum": [
"relevance",
"search_volume",
"competition_index",
"low_top_of_page_bid",
"high_top_of_page_bid"
],
"type": "string",
"description": "Sort related keyword ideas by relevance, search volume, competition, or bid metric. With resultId, sorts stored rows before paging."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "1-20 seed keywords to find related keyword ideas for. Examples: [\"running shoes\", \"nike running\", \"marathon training\"]"
},
"language": {
"type": "string",
"minLength": 1,
"description": "Target-market language for keyword research, e.g. \"English\" or \"German\". No Account-derived default; omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Target-market country for keyword research, e.g. \"United States\" or \"Germany\". No Account-derived default; omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous research_find_keywords call. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find keyword ideas",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Get volume, CPC, competition, bid and monthly trend metrics for 1-1000 known keywords. Supply target-market location/language; no targeting is inferred from a Google Ads Account. Omitted values use provider defaults (United States/English on the Google backend). Google Keyword Planner supplies the market estimates when the user has a usable Google Ads Account, DataForSEO otherwise. These are not Account campaign metrics. Results expire after 24 hours. Pass resultId with page/pageSize/sortBy for stored pages; omit keywords/location/language. Paging or sorting stored rows does not refetch the provider. Start a fresh lookup after expiry.
The description explains the capability, when to use it, and what to expect.
Inputs82/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keywords
1-1000 known keywords to get search volume for. Examples: ["running shoes", "nike running", "marathon training"]
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
Target-market language for search volume research, e.g. "English" or "German". No Account-derived default; omit when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
Target-market country for search volume research, e.g. "United States" or "Germany". No Account-derived default; omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page to return. Defaults to 10.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
sortBy
Sort known keywords by relevance, search volume, competition, or bid metric. With resultId, sorts stored rows before paging.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "research_get_search_volume",
"title": "Get keyword search volumes",
"description": "Get volume, CPC, competition, bid and monthly trend metrics for 1-1000 known keywords. Supply target-market location/language; no targeting is inferred from a Google Ads Account. Omitted values use provider defaults (United States/English on the Google backend). Google Keyword Planner supplies the market estimates when the user has a usable Google Ads Account, DataForSEO otherwise. These are not Account campaign metrics. Results expire after 24 hours. Pass resultId with page/pageSize/sortBy for stored pages; omit keywords/location/language. Paging or sorting stored rows does not refetch the provider. Start a fresh lookup after expiry.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"sortBy": {
"enum": [
"relevance",
"search_volume",
"competition_index",
"low_top_of_page_bid",
"high_top_of_page_bid"
],
"type": "string",
"description": "Sort known keywords by relevance, search volume, competition, or bid metric. With resultId, sorts stored rows before paging."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 1000,
"minItems": 1,
"description": "1-1000 known keywords to get search volume for. Examples: [\"running shoes\", \"nike running\", \"marathon training\"]"
},
"language": {
"type": "string",
"minLength": 1,
"description": "Target-market language for search volume research, e.g. \"English\" or \"German\". No Account-derived default; omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Target-market country for search volume research, e.g. \"United States\" or \"Germany\". No Account-derived default; omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get keyword search volumes",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Forecast impressions, clicks, CTR, average CPC and cost for keywords at a bid and match type. DataForSEO supplies estimates, not connected-Account performance; no Google Ads Connection is required. bid and monetary results use USD. Pass keywords, bid and match for a fresh forecast; optionally dateInterval and target-market location/language. The server does not infer market targeting from an Account. Results expire after 24 hours. For stored pages/re-sorting, pass resultId with page/pageSize/sortBy and omit all fresh-forecast inputs. Stored paging does not refetch data; after expiry request a new forecast.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keywords
1-1000 known keywords to forecast ad traffic for. Examples: ["running shoes", "nike running", "marathon training"]
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
bid
CPC bid in USD to simulate. Example: 1.50.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match
Keyword match type for the forecast: "exact", "broad", or "phrase".
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateInterval
Forecasting period: "next_week", "next_month", or "next_quarter".
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
Target-market language for ad traffic research, e.g. "English" or "German". No Account-derived default; omit when paging with resultId.
Clear enough to supply this argument.
location
Target-market country for ad traffic research, e.g. "United States" or "Germany". No Account-derived default; omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page to return. Defaults to 10.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
sortBy
Sort forecast rows by relevance, impressions, CTR, average CPC, cost, or clicks. With resultId, sorts stored rows before paging.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "research_estimate_ad_traffic",
"title": "Estimate ad traffic",
"description": "Forecast impressions, clicks, CTR, average CPC and cost for keywords at a bid and match type. DataForSEO supplies estimates, not connected-Account performance; no Google Ads Connection is required. bid and monetary results use USD. Pass keywords, bid and match for a fresh forecast; optionally dateInterval and target-market location/language. The server does not infer market targeting from an Account. Results expire after 24 hours. For stored pages/re-sorting, pass resultId with page/pageSize/sortBy and omit all fresh-forecast inputs. Stored paging does not refetch data; after expiry request a new forecast.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"bid": {
"type": "number",
"description": "CPC bid in USD to simulate. Example: 1.50.",
"exclusiveMinimum": 0
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"match": {
"enum": [
"exact",
"broad",
"phrase"
],
"type": "string",
"description": "Keyword match type for the forecast: \"exact\", \"broad\", or \"phrase\"."
},
"sortBy": {
"enum": [
"relevance",
"impressions",
"ctr",
"average_cpc",
"cost",
"clicks"
],
"type": "string",
"description": "Sort forecast rows by relevance, impressions, CTR, average CPC, cost, or clicks. With resultId, sorts stored rows before paging."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 1000,
"minItems": 1,
"description": "1-1000 known keywords to forecast ad traffic for. Examples: [\"running shoes\", \"nike running\", \"marathon training\"]"
},
"language": {
"type": "string",
"minLength": 1,
"description": "Target-market language for ad traffic research, e.g. \"English\" or \"German\". No Account-derived default; omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Target-market country for ad traffic research, e.g. \"United States\" or \"Germany\". No Account-derived default; omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
},
"dateInterval": {
"enum": [
"next_week",
"next_month",
"next_quarter"
],
"type": "string",
"description": "Forecasting period: \"next_week\", \"next_month\", or \"next_quarter\"."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"columns",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows, each keyed by the names in columns."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "The row fields, in display order."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Estimate ad traffic",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Render a single landing page URL in a real browser and return the JavaScript-rendered DOM, HTTP status, redirect chain and server response timings. Use for content, form and tag checks that a static fetch would miss. Pass the full URL including https://. Optionally set browserPreset to desktop, mobile or tablet (defaults to desktop). For page speed, accessibility or Core Web Vitals use lp_audit_lighthouse; for a visual capture use lp_audit_screenshot.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
url
The full landing page URL to audit, including the scheme. Example: https://acme.com/lp/spring-sale
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
browserPreset
Rendering viewport for the audit: 'desktop', 'mobile', or 'tablet'. Defaults to desktop.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Declare the result fields and their types in the output schema.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result",
"resultCount"
],
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "The page as a real browser rendered it: HTTP status, redirect chain, server timings, the meta tags (title, description, canonical, robots, hreflang), headings and structured data."
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "lp_audit_instant",
"title": "Audit a landing page (instant)",
"description": "Render a single landing page URL in a real browser and return the JavaScript-rendered DOM, HTTP status, redirect chain and server response timings. Use for content, form and tag checks that a static fetch would miss. Pass the full URL including https://. Optionally set browserPreset to desktop, mobile or tablet (defaults to desktop). For page speed, accessibility or Core Web Vitals use lp_audit_lighthouse; for a visual capture use lp_audit_screenshot.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"minLength": 1,
"description": "The full landing page URL to audit, including the scheme. Example: https://acme.com/lp/spring-sale"
},
"browserPreset": {
"enum": [
"desktop",
"mobile",
"tablet"
],
"type": "string",
"description": "Rendering viewport for the audit: 'desktop', 'mobile', or 'tablet'. Defaults to desktop."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result",
"resultCount"
],
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "The page as a real browser rendered it: HTTP status, redirect chain, server timings, the meta tags (title, description, canonical, robots, hreflang), headings and structured data."
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Audit a landing page (instant)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Run a Lighthouse audit on a single landing page URL using Google data: returns Performance, Accessibility, and Best Practices scores with their underlying metrics (including Core Web Vitals). Use this whenever page speed, Core Web Vitals, mobile performance, or accessibility is in question. Pass the full URL (including https://). Set forMobile to true to run the mobile audit (defaults to a desktop audit). Optionally pass categories (an array containing any of 'performance', 'accessibility', 'best_practices') to narrow the audit; omit it to audit all three. For how the page looks on mobile — layout, fold position, or anything visual — use lp_audit_screenshot with browserPreset 'mobile' instead. For the rendered DOM, forms, or tracking tags, use lp_audit_instant instead.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
url
The full landing page URL to audit, including the scheme. Example: https://acme.com/lp/spring-sale
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
forMobile
Run the mobile Lighthouse audit instead of desktop. Defaults to desktop.
Clear enough to supply this argument.
categories
Array of Lighthouse categories to audit. Each item must be one of "performance", "accessibility", "best_practices". Provide one or more; omit to audit all three. SEO is intentionally not available.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "The Lighthouse report: a score from 0 to 1 for each requested category, and the audits behind it."
},
"audited": {
"type": "boolean",
"const": false,
"description": "false when the target page itself failed to load or render — see `pageError` and `guidance`; the audit fields are absent."
},
"guidance": {
"type": "string"
},
"pageError": {
"type": "string"
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "lp_audit_lighthouse",
"title": "Audit a landing page (Lighthouse)",
"description": "Run a Lighthouse audit on a single landing page URL using Google data: returns Performance, Accessibility, and Best Practices scores with their underlying metrics (including Core Web Vitals). Use this whenever page speed, Core Web Vitals, mobile performance, or accessibility is in question. Pass the full URL (including https://). Set forMobile to true to run the mobile audit (defaults to a desktop audit). Optionally pass categories (an array containing any of 'performance', 'accessibility', 'best_practices') to narrow the audit; omit it to audit all three. For how the page looks on mobile — layout, fold position, or anything visual — use lp_audit_screenshot with browserPreset 'mobile' instead. For the rendered DOM, forms, or tracking tags, use lp_audit_instant instead.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"minLength": 1,
"description": "The full landing page URL to audit, including the scheme. Example: https://acme.com/lp/spring-sale"
},
"forMobile": {
"type": "boolean",
"description": "Run the mobile Lighthouse audit instead of desktop. Defaults to desktop."
},
"categories": {
"type": "array",
"items": {
"enum": [
"performance",
"accessibility",
"best_practices"
],
"type": "string"
},
"minItems": 1,
"description": "Array of Lighthouse categories to audit. Each item must be one of \"performance\", \"accessibility\", \"best_practices\". Provide one or more; omit to audit all three. SEO is intentionally not available."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "The Lighthouse report: a score from 0 to 1 for each requested category, and the audits behind it."
},
"audited": {
"type": "boolean",
"const": false,
"description": "false when the target page itself failed to load or render — see `pageError` and `guidance`; the audit fields are absent."
},
"guidance": {
"type": "string"
},
"pageError": {
"type": "string"
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Audit a landing page (Lighthouse)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Capture a screenshot of a single landing page URL, rendered in a real browser. The capture is returned inline as an image you can look at directly — judge the page from it rather than asking the user for a screenshot. Use this for any visual or design judgment about the page — fold position, hero appeal, layout, color contrast, mobile rendering, or professionalism. Pass the full URL (including https://). Set fullPage to true to capture the entire scrollable page (defaults to the viewport only). Optionally set browserPreset to 'desktop', 'mobile', or 'tablet' (defaults to desktop).
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
url
The full landing page URL to capture, including the scheme. Example: https://acme.com/lp/spring-sale
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fullPage
Capture the entire scrollable page instead of just the viewport. Defaults to viewport only.
Clear enough to supply this argument.
browserPreset
Rendering viewport for the screenshot: 'desktop', 'mobile', or 'tablet'. Defaults to desktop.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result",
"resultCount"
],
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"full_page",
"browser_preset"
],
"properties": {
"url": {
"type": "string",
"description": "The page captured."
},
"full_page": {
"type": "boolean",
"description": "true for the whole scrollable page, false for the viewport."
},
"browser_preset": {
"type": "string",
"description": "The viewport: desktop, mobile or tablet."
}
},
"additionalProperties": {}
},
"description": "What was captured. The screenshot itself is the image in the result's content."
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "lp_audit_screenshot",
"title": "Screenshot a landing page",
"description": "Capture a screenshot of a single landing page URL, rendered in a real browser. The capture is returned inline as an image you can look at directly — judge the page from it rather than asking the user for a screenshot. Use this for any visual or design judgment about the page — fold position, hero appeal, layout, color contrast, mobile rendering, or professionalism. Pass the full URL (including https://). Set fullPage to true to capture the entire scrollable page (defaults to the viewport only). Optionally set browserPreset to 'desktop', 'mobile', or 'tablet' (defaults to desktop).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"minLength": 1,
"description": "The full landing page URL to capture, including the scheme. Example: https://acme.com/lp/spring-sale"
},
"fullPage": {
"type": "boolean",
"description": "Capture the entire scrollable page instead of just the viewport. Defaults to viewport only."
},
"browserPreset": {
"enum": [
"desktop",
"mobile",
"tablet"
],
"type": "string",
"description": "Rendering viewport for the screenshot: 'desktop', 'mobile', or 'tablet'. Defaults to desktop."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result",
"resultCount"
],
"properties": {
"result": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"full_page",
"browser_preset"
],
"properties": {
"url": {
"type": "string",
"description": "The page captured."
},
"full_page": {
"type": "boolean",
"description": "true for the whole scrollable page, false for the viewport."
},
"browser_preset": {
"type": "string",
"description": "The viewport: desktop, mobile or tablet."
}
},
"additionalProperties": {}
},
"description": "What was captured. The screenshot itself is the image in the result's content."
},
"resultCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries in result."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Screenshot a landing page",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Inventory the JavaScript, CSS, and image resources loaded by a single landing page URL, with load timing. Use this to detect conversion-tracking setup — Google Ads tags, analytics, pixels, call-tracking, and event-tracking scripts — or to find broken and slow resources. Pass the full URL (including https://). Optionally set resourceType to 'script', 'stylesheet', 'image', or 'broken' to filter the inventory (defaults to all resource types).
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
url
The full landing page URL to inspect, including the scheme. Example: https://acme.com/lp/spring-sale
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
resourceType
Filter the inventory to one resource type: 'script', 'stylesheet', 'image', or 'broken'. Defaults to all types.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Fetch the Google search results page (SERP) for one keyword, filtered by block type (organic, paid, featured_snippet, local_pack, people_also_ask, shopping and others). Pass itemTypes explicitly; ['paid'] returns the sponsored results with each advertiser's domain, which answers who is advertising on a keyword. Returns paginated SERP items plus a resultId; call again with the same resultId, page and pageSize to read further pages. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId. Add 'ai_overview' for Google's AI Overview text and the pages it cites (citedDomain says whether a domain is among them); with 'people_also_ask', paaDepth opens the answers and their sources. Results combine Google data with third-party aggregated data.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
keyword
The single search query to pull SERP results for. Example: "bilan de compétences CPF". Required for a new search; omit when paging with resultId.
Clear enough to supply this argument.
itemTypes
SERP block types to return, e.g. ["organic"] or ["paid"]. Required for a new search; omit when paging with resultId. Ordering note: if the first element is anything other than "organic", results are ordered by that first type.
Clear enough to supply this argument.
location
Country for the SERP (e.g. "United States", "Germany", "France"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId.
Clear enough to supply this argument.
language
Language for the SERP (e.g. "English", "German", "French"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId.
Clear enough to supply this argument.
device
Device to emulate for the SERP. Defaults to desktop.
Clear enough to supply this argument.
paaDepth
With "people_also_ask" in itemTypes: how many levels of questions to open, each answer with its source page. Each level costs more; omit for the questions as shown.
Clear enough to supply this argument.
citedDomain
With "ai_overview" in itemTypes: a domain to look for among the AI Overview's cited pages, e.g. "acme.com". The result says whether it (or a subdomain) is cited.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Clear enough to supply this argument.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"items": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The page it links to."
},
"type": {
"type": [
"string",
"null"
],
"description": "What the entry is: paid, organic, people_also_ask and so on."
},
"title": {
"type": [
"string",
"null"
],
"description": "The headline."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The site it links to."
},
"position": {
"type": [
"string",
"null"
],
"description": "left or right side of the page."
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "The URL path Google shows."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among entries of the same type."
},
"description": {
"type": [
"string",
"null"
],
"description": "The text under the headline."
},
"website_name": {
"type": [
"string",
"null"
],
"description": "The site's name as Google shows it."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position on the whole page."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The page's entries in order; each type adds its own fields (links, price, rating on paid ads)."
},
"keyword": {
"type": [
"string",
"null"
],
"description": "The search query."
},
"datetime": {
"type": [
"string",
"null"
],
"description": "When the page was read (UTC)."
},
"check_url": {
"type": [
"string",
"null"
],
"description": "The same search on Google, to check by hand."
},
"item_types": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The entry types on the page."
},
"items_count": {
"type": [
"number",
"null"
],
"description": "Entries in items."
},
"se_results_count": {
"type": [
"number",
"null"
],
"description": "Google's estimate of all results for the query."
}
},
"additionalProperties": {}
},
"description": "The results page as Google returned it, its entries in items."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"aiOverview": {
"type": "object",
"required": [
"present",
"text",
"references"
],
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "The summary's text."
},
"present": {
"type": "boolean",
"description": "Whether the page shows an AI summary."
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"domain",
"title",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The cited page."
},
"title": {
"type": [
"string",
"null"
],
"description": "The cited page's title."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The cited site."
}
},
"additionalProperties": false
},
"description": "Sources the summary cites."
},
"citesDomain": {
"type": "boolean",
"description": "With citedDomain: whether a source is on it."
}
},
"description": "The AI summary on the results page, when asked for.",
"additionalProperties": false
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
},
"peopleAlsoAsk": {
"type": "array",
"items": {
"type": "object",
"required": [
"question",
"answer",
"url",
"domain"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The answer's source page."
},
"answer": {
"type": [
"string",
"null"
],
"description": "The answer shown under it."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The answer's source site."
},
"question": {
"type": "string",
"description": "The question."
}
},
"additionalProperties": false
},
"description": "People also ask questions, when asked for."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "serp_results",
"title": "Get Google search results (SERP)",
"description": "Fetch the Google search results page (SERP) for one keyword, filtered by block type (organic, paid, featured_snippet, local_pack, people_also_ask, shopping and others). Pass itemTypes explicitly; ['paid'] returns the sponsored results with each advertiser's domain, which answers who is advertising on a keyword. Returns paginated SERP items plus a resultId; call again with the same resultId, page and pageSize to read further pages. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId. Add 'ai_overview' for Google's AI Overview text and the pages it cites (citedDomain says whether a domain is among them); with 'people_also_ask', paaDepth opens the answers and their sources. Results combine Google data with third-party aggregated data.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"device": {
"enum": [
"desktop",
"mobile"
],
"type": "string",
"description": "Device to emulate for the SERP. Defaults to desktop."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The single search query to pull SERP results for. Example: \"bilan de compétences CPF\". Required for a new search; omit when paging with resultId."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Language for the SERP (e.g. \"English\", \"German\", \"French\"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Country for the SERP (e.g. \"United States\", \"Germany\", \"France\"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId."
},
"paaDepth": {
"type": "integer",
"maximum": 4,
"minimum": 1,
"description": "With \"people_also_ask\" in itemTypes: how many levels of questions to open, each answer with its source page. Each level costs more; omit for the questions as shown."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
},
"itemTypes": {
"type": "array",
"items": {
"enum": [
"organic",
"paid",
"featured_snippet",
"local_pack",
"people_also_ask",
"knowledge_graph",
"answer_box",
"shopping",
"video",
"images",
"top_stories",
"related_searches",
"carousel",
"ai_overview"
],
"type": "string"
},
"minItems": 1,
"description": "SERP block types to return, e.g. [\"organic\"] or [\"paid\"]. Required for a new search; omit when paging with resultId. Ordering note: if the first element is anything other than \"organic\", results are ordered by that first type."
},
"citedDomain": {
"type": "string",
"maxLength": 253,
"minLength": 1,
"description": "With \"ai_overview\" in itemTypes: a domain to look for among the AI Overview's cited pages, e.g. \"acme.com\". The result says whether it (or a subdomain) is cited."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"items": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The page it links to."
},
"type": {
"type": [
"string",
"null"
],
"description": "What the entry is: paid, organic, people_also_ask and so on."
},
"title": {
"type": [
"string",
"null"
],
"description": "The headline."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The site it links to."
},
"position": {
"type": [
"string",
"null"
],
"description": "left or right side of the page."
},
"breadcrumb": {
"type": [
"string",
"null"
],
"description": "The URL path Google shows."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among entries of the same type."
},
"description": {
"type": [
"string",
"null"
],
"description": "The text under the headline."
},
"website_name": {
"type": [
"string",
"null"
],
"description": "The site's name as Google shows it."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position on the whole page."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The page's entries in order; each type adds its own fields (links, price, rating on paid ads)."
},
"keyword": {
"type": [
"string",
"null"
],
"description": "The search query."
},
"datetime": {
"type": [
"string",
"null"
],
"description": "When the page was read (UTC)."
},
"check_url": {
"type": [
"string",
"null"
],
"description": "The same search on Google, to check by hand."
},
"item_types": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The entry types on the page."
},
"items_count": {
"type": [
"number",
"null"
],
"description": "Entries in items."
},
"se_results_count": {
"type": [
"number",
"null"
],
"description": "Google's estimate of all results for the query."
}
},
"additionalProperties": {}
},
"description": "The results page as Google returned it, its entries in items."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"aiOverview": {
"type": "object",
"required": [
"present",
"text",
"references"
],
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "The summary's text."
},
"present": {
"type": "boolean",
"description": "Whether the page shows an AI summary."
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"domain",
"title",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The cited page."
},
"title": {
"type": [
"string",
"null"
],
"description": "The cited page's title."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The cited site."
}
},
"additionalProperties": false
},
"description": "Sources the summary cites."
},
"citesDomain": {
"type": "boolean",
"description": "With citedDomain: whether a source is on it."
}
},
"description": "The AI summary on the results page, when asked for.",
"additionalProperties": false
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
},
"peopleAlsoAsk": {
"type": "array",
"items": {
"type": "object",
"required": [
"question",
"answer",
"url",
"domain"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The answer's source page."
},
"answer": {
"type": [
"string",
"null"
],
"description": "The answer shown under it."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The answer's source site."
},
"question": {
"type": "string",
"description": "The question."
}
},
"additionalProperties": false
},
"description": "People also ask questions, when asked for."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Google search results (SERP)",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Find domains competing with a specified domain in Google organic search, one row per domain: shared keywords and the average position on them, plus the domain's organic and paid keyword counts, estimated monthly traffic (visits) and what that traffic would cost to buy in USD. These are third-party estimates, not Google's official competitor list or Google Ads auction competitors. For a new lookup, provide domain without a scheme, port, path, query, or fragment (e.g. "acme.com") and omit resultId. Specify the target search-market country and language, reusing known Account context where appropriate; ask the user if unknown. The server does not infer these values from a Google Ads Account, and no Google Ads Connection is required. Returns paginated rows and a resultId for a temporary result that expires after 24 hours. To read another page without fetching again, provide resultId with optional page and pageSize; omit domain, location, language, and limit. Does not modify advertising Accounts or campaigns.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
domain
Domain whose organic-search competitors to find, without a scheme, port, path, query, or fragment. Example: "acme.com". Required for a new lookup; omit when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
Target search-market country for a new competitor lookup (e.g. "United States", "Germany", "France"), not the user's personal location. Reuse known Account context or ask the user if unknown; the server does not infer it from a Google Ads Account. Omit when paging with resultId.
Clear enough to supply this argument.
language
Target search language for a new competitor lookup (e.g. "English", "German", "French"). Reuse known Account context or ask the user if unknown; the server does not infer it from a Google Ads Account. Omit when paging with resultId.
Clear enough to supply this argument.
limit
Competitor domains to fetch for a new lookup. Uses the provider default if omitted. Omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Clear enough to supply this argument.
resultId
Result ID from a previous competitors_for_domain lookup, valid for 24 hours. With resultId, only page and pageSize may also be supplied; omit domain, location, language, and limit. Omit resultId for a new lookup.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Find competitors for a domain",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema84/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"shared_keywords",
"avg_position",
"shared_keywords_traffic",
"organic_keywords",
"organic_traffic",
"organic_traffic_value_usd",
"paid_keywords",
"paid_traffic",
"paid_traffic_cost_usd"
],
"properties": {
"domain": {
"type": "string",
"description": "The competing site."
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "Its average position on those shared keywords."
},
"paid_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly paid visits."
},
"paid_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords it bids on."
},
"organic_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly organic visits."
},
"shared_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords both sites rank for."
},
"organic_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords it ranks for organically."
},
"paid_traffic_cost_usd": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly ad spend for that traffic, in USD."
},
"shared_keywords_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly visits from the shared keywords."
},
"organic_traffic_value_usd": {
"type": [
"number",
"null"
],
"description": "What that organic traffic would cost as ads, in USD."
}
},
"additionalProperties": {}
},
"description": "This page's competitors, one per row."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "competitors_for_domain",
"title": "Find competitors for a domain",
"description": "Find domains competing with a specified domain in Google organic search, one row per domain: shared keywords and the average position on them, plus the domain's organic and paid keyword counts, estimated monthly traffic (visits) and what that traffic would cost to buy in USD. These are third-party estimates, not Google's official competitor list or Google Ads auction competitors. For a new lookup, provide domain without a scheme, port, path, query, or fragment (e.g. \"acme.com\") and omit resultId. Specify the target search-market country and language, reusing known Account context where appropriate; ask the user if unknown. The server does not infer these values from a Google Ads Account, and no Google Ads Connection is required. Returns paginated rows and a resultId for a temporary result that expires after 24 hours. To read another page without fetching again, provide resultId with optional page and pageSize; omit domain, location, language, and limit. Does not modify advertising Accounts or campaigns.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Competitor domains to fetch for a new lookup. Uses the provider default if omitted. Omit when paging with resultId."
},
"domain": {
"type": "string",
"maxLength": 253,
"minLength": 1,
"description": "Domain whose organic-search competitors to find, without a scheme, port, path, query, or fragment. Example: \"acme.com\". Required for a new lookup; omit when paging with resultId."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Target search language for a new competitor lookup (e.g. \"English\", \"German\", \"French\"). Reuse known Account context or ask the user if unknown; the server does not infer it from a Google Ads Account. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Target search-market country for a new competitor lookup (e.g. \"United States\", \"Germany\", \"France\"), not the user's personal location. Reuse known Account context or ask the user if unknown; the server does not infer it from a Google Ads Account. Omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID from a previous competitors_for_domain lookup, valid for 24 hours. With resultId, only page and pageSize may also be supplied; omit domain, location, language, and limit. Omit resultId for a new lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"shared_keywords",
"avg_position",
"shared_keywords_traffic",
"organic_keywords",
"organic_traffic",
"organic_traffic_value_usd",
"paid_keywords",
"paid_traffic",
"paid_traffic_cost_usd"
],
"properties": {
"domain": {
"type": "string",
"description": "The competing site."
},
"avg_position": {
"type": [
"number",
"null"
],
"description": "Its average position on those shared keywords."
},
"paid_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly paid visits."
},
"paid_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords it bids on."
},
"organic_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly organic visits."
},
"shared_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords both sites rank for."
},
"organic_keywords": {
"type": [
"number",
"null"
],
"description": "Keywords it ranks for organically."
},
"paid_traffic_cost_usd": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly ad spend for that traffic, in USD."
},
"shared_keywords_traffic": {
"type": [
"number",
"null"
],
"description": "Its estimated monthly visits from the shared keywords."
},
"organic_traffic_value_usd": {
"type": [
"number",
"null"
],
"description": "What that organic traffic would cost as ads, in USD."
}
},
"additionalProperties": {}
},
"description": "This page's competitors, one per row."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find competitors for a domain",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Find the advertisers running ads for a given keyword or brand term, using Google Ads Transparency Center data. Pass a single keyword. Returns paginated advertiser rows (including advertiser identifiers) plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Feed an advertiser's identifier or domain into ads_search_live to see the actual ad creatives they are running. Set limit to cap the number of advertisers returned (the data source returns many by default). For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyword
The keyword or brand term to find advertisers for. Example: "running shoes".
Clear enough to supply this argument.
location
Country for the advertiser lookup (e.g. "United States", "Germany", "France"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
Language for the advertiser lookup (e.g. "English", "German", "French"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Clear enough to supply this argument.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "What the row is: ads_advertiser, ads_multi_account_advertiser or ads_domain."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"domain": {
"type": [
"string",
"null"
],
"description": "For ads_domain rows: the advertised domain."
},
"location": {
"type": [
"string",
"null"
],
"description": "The advertiser's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among rows of the same type."
},
"advertisers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": [
"string",
"null"
],
"description": "The account's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the account."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The account's id."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads the account has run."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "For ads_multi_account_advertiser rows: the accounts behind one name."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account's id, what ads_search_live takes in advertiserIds."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position among all rows."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads it has run on Google."
}
},
"additionalProperties": {}
},
"description": "This page's advertisers, best match first."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ads_transparency_advertiser",
"title": "Resolve Ads Transparency advertisers",
"description": "Find the advertisers running ads for a given keyword or brand term, using Google Ads Transparency Center data. Pass a single keyword. Returns paginated advertiser rows (including advertiser identifiers) plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Feed an advertiser's identifier or domain into ads_search_live to see the actual ad creatives they are running. Set limit to cap the number of advertisers returned (the data source returns many by default). For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The keyword or brand term to find advertisers for. Example: \"running shoes\"."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Language for the advertiser lookup (e.g. \"English\", \"German\", \"French\"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Country for the advertiser lookup (e.g. \"United States\", \"Germany\", \"France\"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "What the row is: ads_advertiser, ads_multi_account_advertiser or ads_domain."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"domain": {
"type": [
"string",
"null"
],
"description": "For ads_domain rows: the advertised domain."
},
"location": {
"type": [
"string",
"null"
],
"description": "The advertiser's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among rows of the same type."
},
"advertisers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": [
"string",
"null"
],
"description": "The account's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the account."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The account's id."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads the account has run."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "For ads_multi_account_advertiser rows: the accounts behind one name."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account's id, what ads_search_live takes in advertiserIds."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position among all rows."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads it has run on Google."
}
},
"additionalProperties": {}
},
"description": "This page's advertisers, best match first."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Resolve Ads Transparency advertisers",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Show the ad creatives an advertiser runs or has run, most recently shown first (last_shown), from Google Ads Transparency Center data; rows have no ad text. Identify the advertiser by EXACTLY ONE of: target (their domain, e.g. "acme.com") or advertiserIds (identifiers from ads_transparency_advertiser) — there is no keyword search here; if you only know a brand name, resolve it with ads_transparency_advertiser first, and if you want the ads shown on a search QUERY, use serp_results with itemTypes:['paid'] instead. Returns paginated ad rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by platform ('google_search', 'google_shopping', 'google_maps', 'google_play', 'all'; YouTube ads are in format 'video') or format ('text', 'image', 'video', 'all'). For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.
The description explains the capability, when to use it, and what to expect.
Inputs86/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
target
The advertiser domain whose live ads to fetch, with no scheme or path. Example: "acme.com". For a new search provide exactly one of target or advertiserIds; omit both when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
advertiserIds
Advertiser identifiers returned by ads_transparency_advertiser (max 25). For a new search provide exactly one of target or advertiserIds; omit both when paging with resultId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platform
Filter ads to one platform: 'google_search', 'google_shopping', 'google_maps', 'google_play', or 'all'. YouTube cannot be picked on its own: its ads are among format 'video'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
format
Filter ads to one creative format: 'text', 'image', 'video', or 'all'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
Country for the ad search (e.g. "United States", "Germany", "France"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId.
Clear enough to supply this argument.
language
Language for the ad search (e.g. "English", "German", "French"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The ad's page in the Ads Transparency Center."
},
"type": {
"type": [
"string",
"null"
],
"description": "Always ads_search."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"format": {
"type": [
"string",
"null"
],
"description": "text, image or video."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"last_shown": {
"type": [
"string",
"null"
],
"description": "When Google last showed it (UTC)."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
},
"creative_id": {
"type": [
"string",
"null"
],
"description": "The ad's id."
},
"first_shown": {
"type": [
"string",
"null"
],
"description": "When Google first showed it (UTC)."
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "A page that renders the ad, when there is no image."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account that runs it."
},
"preview_image": {
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The preview image."
},
"width": {
"type": [
"number",
"null"
],
"description": "Its width in pixels."
},
"height": {
"type": [
"number",
"null"
],
"description": "Its height in pixels."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "A picture of the ad, when Google has one."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
}
},
"additionalProperties": {}
},
"description": "This page's ads, most recently shown first."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ads_search_live",
"title": "Browse Ads Transparency Center ads",
"description": "Show the ad creatives an advertiser runs or has run, most recently shown first (last_shown), from Google Ads Transparency Center data; rows have no ad text. Identify the advertiser by EXACTLY ONE of: target (their domain, e.g. \"acme.com\") or advertiserIds (identifiers from ads_transparency_advertiser) — there is no keyword search here; if you only know a brand name, resolve it with ads_transparency_advertiser first, and if you want the ads shown on a search QUERY, use serp_results with itemTypes:['paid'] instead. Returns paginated ad rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by platform ('google_search', 'google_shopping', 'google_maps', 'google_play', 'all'; YouTube ads are in format 'video') or format ('text', 'image', 'video', 'all'). For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"format": {
"enum": [
"all",
"text",
"image",
"video"
],
"type": "string",
"description": "Filter ads to one creative format: 'text', 'image', 'video', or 'all'."
},
"target": {
"type": "string",
"maxLength": 253,
"minLength": 1,
"description": "The advertiser domain whose live ads to fetch, with no scheme or path. Example: \"acme.com\". For a new search provide exactly one of target or advertiserIds; omit both when paging with resultId."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Language for the ad search (e.g. \"English\", \"German\", \"French\"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Country for the ad search (e.g. \"United States\", \"Germany\", \"France\"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"platform": {
"enum": [
"all",
"google_play",
"google_maps",
"google_search",
"google_shopping"
],
"type": "string",
"description": "Filter ads to one platform: 'google_search', 'google_shopping', 'google_maps', 'google_play', or 'all'. YouTube cannot be picked on its own: its ads are among format 'video'."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
},
"advertiserIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 25,
"minItems": 1,
"description": "Advertiser identifiers returned by ads_transparency_advertiser (max 25). For a new search provide exactly one of target or advertiserIds; omit both when paging with resultId."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The ad's page in the Ads Transparency Center."
},
"type": {
"type": [
"string",
"null"
],
"description": "Always ads_search."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"format": {
"type": [
"string",
"null"
],
"description": "text, image or video."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"last_shown": {
"type": [
"string",
"null"
],
"description": "When Google last showed it (UTC)."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
},
"creative_id": {
"type": [
"string",
"null"
],
"description": "The ad's id."
},
"first_shown": {
"type": [
"string",
"null"
],
"description": "When Google first showed it (UTC)."
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "A page that renders the ad, when there is no image."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account that runs it."
},
"preview_image": {
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The preview image."
},
"width": {
"type": [
"number",
"null"
],
"description": "Its width in pixels."
},
"height": {
"type": [
"number",
"null"
],
"description": "Its height in pixels."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "A picture of the ad, when Google has one."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
}
},
"additionalProperties": {}
},
"description": "This page's ads, most recently shown first."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Browse Ads Transparency Center ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Find the top Google Shopping products for a keyword, using Google data: returns products with title, rank, price, rating, reviews, and a product_id. Pass a single keyword. Returns paginated product rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by priceMin/priceMax and set sortBy to 'review_score', 'price_low_to_high', or 'price_high_to_low'. Set limit to cap the number of products returned (the data source returns many by default). Feed a product_id into shopping_sellers to compare all sellers offering that product. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyword
The product search query to find top Shopping products for. Example: "electric kettle".
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
priceMin
Minimum product price to include, in the account currency.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
priceMax
Maximum product price to include, in the account currency.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
sortBy
Sort products by 'review_score', 'price_low_to_high', or 'price_high_to_low'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
Country for the Shopping search (e.g. "United States", "Germany", "France"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId.
Clear enough to supply this argument.
language
Language for the Shopping search (e.g. "English", "German", "French"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId.
Clear enough to supply this argument.
limit
Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Clear enough to supply this argument.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get top Google Shopping products",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema64/100
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "shopping_top_products",
"title": "Get top Google Shopping products",
"description": "Find the top Google Shopping products for a keyword, using Google data: returns products with title, rank, price, rating, reviews, and a product_id. Pass a single keyword. Returns paginated product rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by priceMin/priceMax and set sortBy to 'review_score', 'price_low_to_high', or 'price_high_to_low'. Set limit to cap the number of products returned (the data source returns many by default). Feed a product_id into shopping_sellers to compare all sellers offering that product. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set."
},
"sortBy": {
"enum": [
"review_score",
"price_low_to_high",
"price_high_to_low"
],
"type": "string",
"description": "Sort products by 'review_score', 'price_low_to_high', or 'price_high_to_low'."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The product search query to find top Shopping products for. Example: \"electric kettle\"."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Language for the Shopping search (e.g. \"English\", \"German\", \"French\"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Country for the Shopping search (e.g. \"United States\", \"Germany\", \"France\"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"priceMax": {
"type": "number",
"minimum": 0,
"description": "Maximum product price to include, in the account currency."
},
"priceMin": {
"type": "number",
"minimum": 0,
"description": "Minimum product price to include, in the account currency."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get top Google Shopping products",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the sellers offering a specific Google Shopping product, with each seller's price, shipping, special offers and ratings. Use to compare prices across sellers for one product. Pass a productId from shopping_top_products. Returns paginated seller rows plus a resultId; call again with the same resultId, page and pageSize to read further pages. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
productId
The product_id returned by shopping_top_products, identifying the product whose sellers to list. Required for a new lookup; omit when paging with resultId.
Clear enough to supply this argument.
location
Country for the seller lookup (e.g. "United States", "Germany", "France"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId.
Clear enough to supply this argument.
language
Language for the seller lookup (e.g. "English", "German", "French"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId.
Clear enough to supply this argument.
page
Page number to return. Defaults to 1.
Clear enough to supply this argument.
pageSize
Rows per page to return. Defaults to 10.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
resultId
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "shopping_sellers",
"title": "Get Google Shopping sellers",
"description": "List the sellers offering a specific Google Shopping product, with each seller's price, shipping, special offers and ratings. Use to compare prices across sellers for one product. Pass a productId from shopping_top_products. Returns paginated seller rows plus a resultId; call again with the same resultId, page and pageSize to read further pages. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number to return. Defaults to 1."
},
"language": {
"type": "string",
"minLength": 1,
"description": "Language for the seller lookup (e.g. \"English\", \"German\", \"French\"). Specify the intended search language; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user. Omit when paging with resultId."
},
"location": {
"type": "string",
"minLength": 1,
"description": "Country for the seller lookup (e.g. \"United States\", \"Germany\", \"France\"). Specify the intended search-market country; the server does not infer it from a Google Ads Account. Reuse known market context or ask the user; do not omit location or assume worldwide on fresh searches. Omit when paging with resultId."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page to return. Defaults to 10."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
},
"productId": {
"type": "string",
"minLength": 1,
"description": "The product_id returned by shopping_top_products, identifying the product whose sellers to list. Required for a new lookup; omit when paging with resultId."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expiresAt",
"page",
"pageSize",
"resultId",
"rowCount",
"totalPages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "This page's rows."
},
"pageSize": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"resultId": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and pageSize, reads another page without a new lookup."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then resultId reads its other pages for free."
},
"totalPages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this pageSize."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Google Shopping sellers",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Search the public Meta Ad Library (Facebook and Instagram) by keyword to find live and past ads across advertisers, for competitor and market research. Pass query; by default it matches the words together as written, and match "all_words" finds every word anywhere in the ad. Optionally countries (two-letter ISO codes), adActiveStatus (active, inactive, all) and mediaType (image, video, meme, none, all). Each result carries the creative text (body, headline, CTA), media URLs, advertiser page name and id, publisher platforms and run dates; thumbnails render inline (up to 12 per call). When every country passed is in the EU, EEA or UK, rows also include Meta's official transparency fields (audience reach, targeting, payer) and are marked dataSource="official"; otherwise those fields are absent. Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Keyword or phrase to search the Meta Ad Library for.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match
phrase (default): the words together, in this order. all_words: every word somewhere in the ad, in any order.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
countries
Two-letter ISO country codes to scope results, e.g. ["US","GB"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adActiveStatus
Filter by delivery status: 'active', 'inactive', or 'all'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
mediaType
Filter by creative media type.
Explain the meaning of this value, not just its name.
includeThumbnailData
Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad.
Clear enough to supply this argument.
pageSize
Rows per page, at most 100. Defaults to 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Search the Meta Ad Library",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema89/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_ad_library_search",
"title": "Search the Meta Ad Library",
"description": "Search the public Meta Ad Library (Facebook and Instagram) by keyword to find live and past ads across advertisers, for competitor and market research. Pass query; by default it matches the words together as written, and match \"all_words\" finds every word anywhere in the ad. Optionally countries (two-letter ISO codes), adActiveStatus (active, inactive, all) and mediaType (image, video, meme, none, all). Each result carries the creative text (body, headline, CTA), media URLs, advertiser page name and id, publisher platforms and run dates; thumbnails render inline (up to 12 per call). When every country passed is in the EU, EEA or UK, rows also include Meta's official transparency fields (audience reach, targeting, payer) and are marked dataSource=\"official\"; otherwise those fields are absent. Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"match": {
"enum": [
"phrase",
"all_words"
],
"type": "string",
"description": "phrase (default): the words together, in this order. all_words: every word somewhere in the ad, in any order."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Keyword or phrase to search the Meta Ad Library for."
},
"pageSize": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Rows per page, at most 100. Defaults to 25."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "Two-letter ISO country codes to scope results, e.g. [\"US\",\"GB\"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer)."
},
"mediaType": {
"enum": [
"all",
"image",
"video",
"meme",
"none"
],
"type": "string",
"description": "Filter by creative media type."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"adActiveStatus": {
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Filter by delivery status: 'active', 'inactive', or 'all'."
},
"includeThumbnailData": {
"type": "boolean",
"description": "Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search the Meta Ad Library",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Resolve a brand or company name to its Meta Ad Library advertiser page id(s) — the entry point for pulling a specific competitor's ads. Pass query (the brand/company name); optionally countries (two-letter ISO codes). Returns advertiser rows with pageId, pageName, page categories, verification, and follower counts. Feed the pageId into meta_ad_library_advertiser_ads to list that advertiser's ads. This name lookup is best-effort — it can return nothing or fail for niche/ambiguous brands. If it does, resolve the advertiser another way: run meta_ad_library_search scoped to the target countries (e.g. ["DE"]) and read pageId off the rows, or pass the advertiser's known Facebook Page ID straight to meta_ad_library_advertiser_ads — the resolver is not required. Paginate with pageSize; to get the next page, pass the returned nextPageToken back as the pageToken argument.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Brand or company name to look up its advertiser page id(s).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
countries
Two-letter ISO country codes to scope results, e.g. ["US","GB"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page, at most 100. Defaults to 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Find Meta Ad Library advertisers",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema84/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"likes": {
"type": [
"number",
"null"
],
"description": "The Page's likes."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Meta verified the Page."
},
"igUsername": {
"type": [
"string",
"null"
],
"description": "The linked Instagram account."
},
"igFollowers": {
"type": [
"number",
"null"
],
"description": "Followers of that Instagram account."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
}
},
"additionalProperties": {}
},
"description": "This page of advertisers, closest name match first."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_ad_library_advertisers",
"title": "Find Meta Ad Library advertisers",
"description": "Resolve a brand or company name to its Meta Ad Library advertiser page id(s) — the entry point for pulling a specific competitor's ads. Pass query (the brand/company name); optionally countries (two-letter ISO codes). Returns advertiser rows with pageId, pageName, page categories, verification, and follower counts. Feed the pageId into meta_ad_library_advertiser_ads to list that advertiser's ads. This name lookup is best-effort — it can return nothing or fail for niche/ambiguous brands. If it does, resolve the advertiser another way: run meta_ad_library_search scoped to the target countries (e.g. [\"DE\"]) and read pageId off the rows, or pass the advertiser's known Facebook Page ID straight to meta_ad_library_advertiser_ads — the resolver is not required. Paginate with pageSize; to get the next page, pass the returned nextPageToken back as the pageToken argument.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "Brand or company name to look up its advertiser page id(s)."
},
"pageSize": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Rows per page, at most 100. Defaults to 25."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "Two-letter ISO country codes to scope results, e.g. [\"US\",\"GB\"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"likes": {
"type": [
"number",
"null"
],
"description": "The Page's likes."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Meta verified the Page."
},
"igUsername": {
"type": [
"string",
"null"
],
"description": "The linked Instagram account."
},
"igFollowers": {
"type": [
"number",
"null"
],
"description": "Followers of that Instagram account."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
}
},
"additionalProperties": {}
},
"description": "This page of advertisers, closest name match first."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find Meta Ad Library advertisers",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the ads a specific advertiser is running or has run in the public Meta Ad Library. Pass pageId (from meta_ad_library_advertisers, from a meta_ad_library_search row, or a known Facebook Page id); optionally countries (two-letter ISO codes) and adActiveStatus (active, inactive, all). Each result carries the creative text, media URLs, publisher platforms and run dates; thumbnails render inline (up to 12 per call). EU, EEA and UK country scopes add Meta's official transparency fields (audience reach, targeting, payer), marked dataSource="official". Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageId
The advertiser page id, from meta_ad_library_advertisers.
Clear enough to supply this argument.
countries
Two-letter ISO country codes to scope results, e.g. ["US","GB"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adActiveStatus
Filter by delivery status: 'active', 'inactive', or 'all'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
includeThumbnailData
Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad.
Clear enough to supply this argument.
pageSize
Rows per page, at most 100. Defaults to 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "List an advertiser's Ad Library ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema88/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_ad_library_advertiser_ads",
"title": "List an advertiser's Ad Library ads",
"description": "List the ads a specific advertiser is running or has run in the public Meta Ad Library. Pass pageId (from meta_ad_library_advertisers, from a meta_ad_library_search row, or a known Facebook Page id); optionally countries (two-letter ISO codes) and adActiveStatus (active, inactive, all). Each result carries the creative text, media URLs, publisher platforms and run dates; thumbnails render inline (up to 12 per call). EU, EEA and UK country scopes add Meta's official transparency fields (audience reach, targeting, payer), marked dataSource=\"official\". Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"pageId"
],
"properties": {
"pageId": {
"type": "string",
"minLength": 1,
"description": "The advertiser page id, from meta_ad_library_advertisers."
},
"pageSize": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Rows per page, at most 100. Defaults to 25."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "Two-letter ISO country codes to scope results, e.g. [\"US\",\"GB\"]. Omit for all countries. Scoping every code to the EU-27, EEA (Iceland/Liechtenstein/Norway), or UK (GB) unlocks Meta's official first-party fields (audience reach, targeting, payer)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"adActiveStatus": {
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Filter by delivery status: 'active', 'inactive', or 'all'."
},
"includeThumbnailData": {
"type": "boolean",
"description": "Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"nextPageToken": {
"type": [
"string",
"null"
],
"description": "Pass as pageToken for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List an advertiser's Ad Library ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Get the full creative and metadata for one Meta Ad Library ad. Pass adArchiveId (from meta_ad_library_search or meta_ad_library_advertiser_ads). Returns the creative text (body, headline, CTA), media URLs, advertiser page, publisher platforms, run dates and countries; the thumbnail renders inline. Returns null if no ad matches the id. Use it to get the visual for an ad found on the official EU path (those rows carry targeting and reach but no inline media). This endpoint returns web-sourced rows (dataSource="web") without audience targeting or reach; for those use meta_ad_library_search or meta_ad_library_advertiser_ads scoped to EU, EEA or UK countries. Media URLs are signed and expire within hours.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adArchiveId
The ad's archive id, from meta_ad_library_search or meta_ad_library_advertiser_ads.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
includeThumbnailData
Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get Meta Ad Library ad detail",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema86/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object"
],
"properties": {
"object": {
"anyOf": [
{
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad, or null when no ad has this id."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_ad_library_ad_detail",
"title": "Get Meta Ad Library ad detail",
"description": "Get the full creative and metadata for one Meta Ad Library ad. Pass adArchiveId (from meta_ad_library_search or meta_ad_library_advertiser_ads). Returns the creative text (body, headline, CTA), media URLs, advertiser page, publisher platforms, run dates and countries; the thumbnail renders inline. Returns null if no ad matches the id. Use it to get the visual for an ad found on the official EU path (those rows carry targeting and reach but no inline media). This endpoint returns web-sourced rows (dataSource=\"web\") without audience targeting or reach; for those use meta_ad_library_search or meta_ad_library_advertiser_ads scoped to EU, EEA or UK countries. Media URLs are signed and expire within hours.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"adArchiveId"
],
"properties": {
"adArchiveId": {
"type": "string",
"minLength": 1,
"description": "The ad's archive id, from meta_ad_library_search or meta_ad_library_advertiser_ads."
},
"includeThumbnailData": {
"type": "boolean",
"description": "Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object"
],
"properties": {
"object": {
"anyOf": [
{
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"imageUrl": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"videoUrl": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"posterUrl": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnailDataUri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with includeThumbnailData."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"pageId": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what meta_ad_library_advertiser_ads takes."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"ctaType": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"linkUrl": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"bodyTruncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; meta_ad_library_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"isActive": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"pageName": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"dataSource": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"targetAges": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"adArchiveId": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what meta_ad_library_ad_detail takes."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"euTotalReach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"targetGender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"pageCategories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"targetLocations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiaryPayers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisherPlatforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"ageCountryGenderReachBreakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad, or null when no ad has this id."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta Ad Library ad detail",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the Meta Ads accounts you have connected in Hypd, with each account's id, name, currency, and timezone. Call this FIRST when working with Meta Ads — it is the entry point and the source of account context (currency, timezone) that you should reuse for the rest of the conversation instead of re-fetching. Use the returned account id (format act_<digits>) as the accountId for every other Meta tool: meta_get_campaigns, meta_get_adsets, meta_get_ads, meta_get_object, meta_get_creative, meta_insights, and meta_get_recommendations. If nothing is returned, no Meta Ads account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations100/100
All four behavior hints are declared.
{
"title": "List Meta ad accounts",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema69/100
Describe the returned fields so an agent can interpret the result.
{
"name": "meta_list_ad_accounts",
"title": "List Meta ad accounts",
"description": "List the Meta Ads accounts you have connected in Hypd, with each account's id, name, currency, and timezone. Call this FIRST when working with Meta Ads — it is the entry point and the source of account context (currency, timezone) that you should reuse for the rest of the conversation instead of re-fetching. Use the returned account id (format act_<digits>) as the accountId for every other Meta tool: meta_get_campaigns, meta_get_adsets, meta_get_ads, meta_get_object, meta_get_creative, meta_insights, and meta_get_recommendations. If nothing is returned, no Meta Ads account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accounts"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"required": [
"adAccountId",
"displayName",
"currency",
"timeZone"
],
"properties": {
"currency": {
"type": [
"string",
"null"
]
},
"timeZone": {
"type": [
"string",
"null"
]
},
"adAccountId": {
"type": "string"
},
"displayName": {
"type": "string"
}
},
"additionalProperties": false
}
},
"planNotice": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta ad accounts",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the campaigns in a Meta Ads account. Use when the user asks what campaigns exist, their status, objective, or budget, or before drilling into ad sets/ads. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields to select which campaign fields to return; paginate with pageSize and the returned nextPageToken. This returns structural data only — for performance use meta_insights at the campaign level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_campaigns",
"title": "Get Meta campaigns",
"description": "List the campaigns in a Meta Ads account. Use when the user asks what campaigns exist, their status, objective, or budget, or before drilling into ad sets/ads. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields to select which campaign fields to return; paginate with pageSize and the returned nextPageToken. This returns structural data only — for performance use meta_insights at the campaign level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta campaigns",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List the ad sets in a Meta Ads account, including targeting, optimization, bidding, and budget settings. Use when the user asks about audiences, placements, optimization goals, or budgets at the ad-set level. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. On accounts with many ad sets the default field set can be too heavy for Meta — if the lookup fails, retry with an explicit minimal fields list (e.g. ["name","status","optimization_goal","daily_budget"]) and a small pageSize, requesting heavy fields like targeting only via meta_get_object on a single ad set. Structural data only — for performance use meta_insights at the adset level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get Meta ad sets",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema63/100
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_adsets",
"title": "Get Meta ad sets",
"description": "List the ad sets in a Meta Ads account, including targeting, optimization, bidding, and budget settings. Use when the user asks about audiences, placements, optimization goals, or budgets at the ad-set level. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. On accounts with many ad sets the default field set can be too heavy for Meta — if the lookup fails, retry with an explicit minimal fields list (e.g. [\"name\",\"status\",\"optimization_goal\",\"daily_budget\"]) and a small pageSize, requesting heavy fields like targeting only via meta_get_object on a single ad set. Structural data only — for performance use meta_insights at the adset level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta ad sets",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the ads in a Meta Ads account, with status and the creative each ad references. Use when the user asks which ads are running or wants to enumerate ads before inspecting creatives or performance. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. For the creative copy/media of a specific ad use meta_get_creative; for performance use meta_insights at the ad level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Clear enough to supply this argument.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_ads",
"title": "Get Meta ads",
"description": "List the ads in a Meta Ads account, with status and the creative each ad references. Use when the user asks which ads are running or wants to enumerate ads before inspecting creatives or performance. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. For the creative copy/media of a specific ad use meta_get_creative; for performance use meta_insights at the ad level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Fetch a single Meta Ads object by id — an account, campaign, ad set, or ad — with its full field set. Use when you already have an object id and need its details rather than listing siblings. REQUIRED: accountId (the act_<digits> id from meta_list_ad_accounts), objectId, and objectType ('campaign', 'adset', or 'ad'; for an act_<digits> objectId it is 'account' and may be omitted). Optionally pass fields to select which fields to return. Example, one campaign: { "accountId": "act_123", "objectId": "1207890", "objectType": "campaign" }. For performance metrics use meta_insights instead.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objectId
The Meta object id (account act_<digits>, campaign, ad set, or ad id).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objectType
The object kind: 'account', 'campaign', 'adset', or 'ad'. Required unless objectId is an act_<digits> account id, which is an account.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get a Meta object",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema72/100
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_object",
"title": "Get a Meta object",
"description": "Fetch a single Meta Ads object by id — an account, campaign, ad set, or ad — with its full field set. Use when you already have an object id and need its details rather than listing siblings. REQUIRED: accountId (the act_<digits> id from meta_list_ad_accounts), objectId, and objectType ('campaign', 'adset', or 'ad'; for an act_<digits> objectId it is 'account' and may be omitted). Optionally pass fields to select which fields to return. Example, one campaign: { \"accountId\": \"act_123\", \"objectId\": \"1207890\", \"objectType\": \"campaign\" }. For performance metrics use meta_insights instead.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"objectId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"objectId": {
"type": "string",
"minLength": 1,
"description": "The Meta object id (account act_<digits>, campaign, ad set, or ad id)."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"objectType": {
"enum": [
"account",
"campaign",
"adset",
"ad"
],
"type": "string",
"description": "The object kind: 'account', 'campaign', 'adset', or 'ad'. Required unless objectId is an act_<digits> account id, which is an account."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a Meta object",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Get the creative for a single Meta ad: headline, primary text, call to action, destination link and media. Use when the user wants to review ad copy and creative or check the landing URL. Pass accountId (act_<digits> from meta_list_ad_accounts) and adId (from meta_get_ads); optionally adFormat to choose the placement rendered in preview_url (defaults to MOBILE_FEED_STANDARD). Media thumbnails are returned inline (up to 12 per call); each media entry also carries url (full-resolution, signed, expires within hours) and permalink_url (stable link). preview_url opens the rendered ad in the browser. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adId
The ad id, from meta_get_ads.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adFormat
Placement for the rendered preview (e.g. MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD). Defaults to MOBILE_FEED_STANDARD.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Clear enough to supply this argument.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get Meta ad creative",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema27/100
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_creative",
"title": "Get Meta ad creative",
"description": "Get the creative for a single Meta ad: headline, primary text, call to action, destination link and media. Use when the user wants to review ad copy and creative or check the landing URL. Pass accountId (act_<digits> from meta_list_ad_accounts) and adId (from meta_get_ads); optionally adFormat to choose the placement rendered in preview_url (defaults to MOBILE_FEED_STANDARD). Media thumbnails are returned inline (up to 12 per call); each media entry also carries url (full-resolution, signed, expires within hours) and permalink_url (stable link). preview_url opens the rendered ad in the browser. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"adId"
],
"properties": {
"adId": {
"type": "string",
"minLength": 1,
"description": "The ad id, from meta_get_ads."
},
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"adFormat": {
"type": "string",
"minLength": 1,
"description": "Placement for the rendered preview (e.g. MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD). Defaults to MOBILE_FEED_STANDARD."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta ad creative",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Meta Ads performance: spend, impressions, reach, clicks, CTR, CPC, CPM, conversions and ROAS. Use for performance questions about a Meta ad account, campaign, ad set or ad. Requires accountId (act_<digits> from meta_list_ad_accounts), level (account/campaign/adset/ad) and either since + until (YYYY-MM-DD) or datePreset. Example: {"accountId":"act_123","level":"campaign","since":"2026-06-01","until":"2026-06-30"}. objectId defaults to the Meta ad account; set it for one campaign, ad set or ad. breakdowns segment metrics (e.g. publisher_platform, age, gender, country); fields selects metrics. Monetary values use the Meta ad account currency returned by meta_list_ad_accounts. Returns raw metrics without server-side analysis; each row's key_results counts every result once (e.g. purchase from omni_purchase), so never sum Meta's overlapping action names. After a rate-limit error, call sequentially and retry after the indicated wait.
The description explains the capability, when to use it, and what to expect.
Inputs70/100
12 of 14 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objectId
The object to measure: a campaign, ad set, or ad id, or the account's act_<digits> id. Defaults to accountId, so omit it to measure the whole account at the given level.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
level
Aggregation level: 'account', 'campaign', 'adset', or 'ad'.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
timeRange › since
Not provided
Missing description. Explain what this value means and how to supply it.
timeRange › until
Not provided
Missing description. Explain what this value means and how to supply it.
since
Start of the date window, YYYY-MM-DD. Same as timeRange.since; use one or the other.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
until
End of the date window, YYYY-MM-DD. Same as timeRange.until.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
datePreset
Relative window instead of timeRange (e.g. 'last_7d', 'last_30d').
Clear enough to supply this argument.
breakdowns
Segment dimensions (e.g. publisher_platform, platform_position, age, gender, country, impression_device). region and hourly_stats_aggregated_by_advertiser_time_zone (hour of day) each work only on their own.
Clear enough to supply this argument.
timeIncrement
Splits the window into rows by time: 1 for one row per day, 7 per week (any number of days up to 90), 'monthly' per calendar month, or 'all_days', the default, for one row for the whole window.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
actionBreakdowns
Action dimensions for conversion breakdowns.
Explain the meaning of this value, not just its name.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Clear enough to supply this argument.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_insights",
"title": "Get Meta insights",
"description": "Meta Ads performance: spend, impressions, reach, clicks, CTR, CPC, CPM, conversions and ROAS. Use for performance questions about a Meta ad account, campaign, ad set or ad. Requires accountId (act_<digits> from meta_list_ad_accounts), level (account/campaign/adset/ad) and either since + until (YYYY-MM-DD) or datePreset. Example: {\"accountId\":\"act_123\",\"level\":\"campaign\",\"since\":\"2026-06-01\",\"until\":\"2026-06-30\"}. objectId defaults to the Meta ad account; set it for one campaign, ad set or ad. breakdowns segment metrics (e.g. publisher_platform, age, gender, country); fields selects metrics. Monetary values use the Meta ad account currency returned by meta_list_ad_accounts. Returns raw metrics without server-side analysis; each row's key_results counts every result once (e.g. purchase from omni_purchase), so never sum Meta's overlapping action names. After a rate-limit error, call sequentially and retry after the indicated wait.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"level"
],
"properties": {
"level": {
"enum": [
"account",
"campaign",
"adset",
"ad"
],
"type": "string",
"description": "Aggregation level: 'account', 'campaign', 'adset', or 'ad'."
},
"since": {
"type": "string",
"minLength": 1,
"description": "Start of the date window, YYYY-MM-DD. Same as timeRange.since; use one or the other."
},
"until": {
"type": "string",
"minLength": 1,
"description": "End of the date window, YYYY-MM-DD. Same as timeRange.until."
},
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"objectId": {
"type": "string",
"minLength": 1,
"description": "The object to measure: a campaign, ad set, or ad id, or the account's act_<digits> id. Defaults to accountId, so omit it to measure the whole account at the given level."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"timeRange": {
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string",
"minLength": 1
},
"until": {
"type": "string",
"minLength": 1
}
},
"description": "Date window as { since, until } in YYYY-MM-DD."
},
"breakdowns": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Segment dimensions (e.g. publisher_platform, platform_position, age, gender, country, impression_device). region and hourly_stats_aggregated_by_advertiser_time_zone (hour of day) each work only on their own."
},
"datePreset": {
"type": "string",
"minLength": 1,
"description": "Relative window instead of timeRange (e.g. 'last_7d', 'last_30d')."
},
"timeIncrement": {
"anyOf": [
{
"type": "integer",
"maximum": 90,
"minimum": 1
},
{
"enum": [
"monthly",
"all_days"
],
"type": "string"
}
],
"description": "Splits the window into rows by time: 1 for one row per day, 7 per week (any number of days up to 90), 'monthly' per calendar month, or 'all_days', the default, for one row for the whole window."
},
"actionBreakdowns": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Action dimensions for conversion breakdowns."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta insights",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Get Meta's own native recommendations and Opportunity Score for an object (account, campaign, ad set, or ad). Use when the user asks what Meta suggests improving, or you want the platform's optimization opportunities. Pass accountId (the act_<digits> id from meta_list_ad_accounts the object belongs to) and objectId, and optionally level (defaults to account). These are Meta-generated suggestions — present them as the platform's recommendations, and pair with meta_insights for the underlying numbers.
The description explains the capability, when to use it, and what to expect.
Inputs67/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objectId
The object to get recommendations for (account, campaign, ad set, or ad id).
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
level
Object level. Defaults to account.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Declare the result fields and their types in the output schema.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_recommendations",
"title": "Get Meta recommendations",
"description": "Get Meta's own native recommendations and Opportunity Score for an object (account, campaign, ad set, or ad). Use when the user asks what Meta suggests improving, or you want the platform's optimization opportunities. Pass accountId (the act_<digits> id from meta_list_ad_accounts the object belongs to) and objectId, and optionally level (defaults to account). These are Meta-generated suggestions — present them as the platform's recommendations, and pair with meta_insights for the underlying numbers.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"objectId"
],
"properties": {
"level": {
"enum": [
"account",
"campaign",
"adset",
"ad"
],
"type": "string",
"description": "Object level. Defaults to account."
},
"objectId": {
"type": "string",
"minLength": 1,
"description": "The object to get recommendations for (account, campaign, ad set, or ad id)."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta recommendations",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Return the change history for a Meta Ads account — what changed and when (campaign/ad set edits, budget, targeting, creative, status). Use when the user asks 'what changed' or to investigate a sudden performance shift. Pass accountId (the act_<digits> id from meta_list_ad_accounts); optionally narrow with since/until (YYYY-MM-DD). Paginate with pageSize and the returned nextPageToken. On busy accounts the change history is a heavy read — if the lookup fails, retry with a narrower since/until window and a small pageSize.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Clear enough to supply this argument.
since
Start date YYYY-MM-DD (optional).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
until
End date YYYY-MM-DD (optional).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_activities",
"title": "Get Meta change history",
"description": "Return the change history for a Meta Ads account — what changed and when (campaign/ad set edits, budget, targeting, creative, status). Use when the user asks 'what changed' or to investigate a sudden performance shift. Pass accountId (the act_<digits> id from meta_list_ad_accounts); optionally narrow with since/until (YYYY-MM-DD). Paginate with pageSize and the returned nextPageToken. On busy accounts the change history is a heavy read — if the lookup fails, retry with a narrower since/until window and a small pageSize.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"since": {
"type": "string",
"minLength": 1,
"description": "Start date YYYY-MM-DD (optional)."
},
"until": {
"type": "string",
"minLength": 1,
"description": "End date YYYY-MM-DD (optional)."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta change history",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
List the Facebook/Instagram Pages reachable from a Meta Ads account. Use this to get a pageId before listing lead forms. Pass accountId (act_<digits> from meta_list_ad_accounts). Paginate with pageSize and nextPageToken. If missingScopes is returned, the connection needs to grant the listed permission — tell the user to reconnect Meta Ads.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_pages",
"title": "List Meta pages",
"description": "List the Facebook/Instagram Pages reachable from a Meta Ads account. Use this to get a pageId before listing lead forms. Pass accountId (act_<digits> from meta_list_ad_accounts). Paginate with pageSize and nextPageToken. If missingScopes is returned, the connection needs to grant the listed permission — tell the user to reconnect Meta Ads.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta pages",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
List the lead-generation forms on a Page. Fire this before retrieving submissions. Pass accountId (act_<digits> from meta_list_ad_accounts, to scope the call) and pageId (from meta_list_pages). Needs the leads_retrieval permission plus Page Lead Access; if missingScopes is returned, surface that the connection must grant it — return what is available, do not treat it as an error. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageId
The page id, from meta_list_pages.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "List Meta lead forms",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema58/100
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_lead_forms",
"title": "List Meta lead forms",
"description": "List the lead-generation forms on a Page. Fire this before retrieving submissions. Pass accountId (act_<digits> from meta_list_ad_accounts, to scope the call) and pageId (from meta_list_pages). Needs the leads_retrieval permission plus Page Lead Access; if missingScopes is returned, surface that the connection must grant it — return what is available, do not treat it as an error. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"pageId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageId": {
"type": "string",
"minLength": 1,
"description": "The page id, from meta_list_pages."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta lead forms",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List the datasets/pixels on a Meta Ads account, for conversion-tracking context. Use when checking pixel inventory before diagnosing conversion tracking. Pass accountId (act_<digits> from meta_list_ad_accounts). To answer whether pixels are firing, pass includeEventCounts: each pixel gets the events it received over the last eventCountDays (1-7, default 7), each split into browser (the pixel) and server (Conversions API). Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Clear enough to supply this argument.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Clear enough to supply this argument.
includeEventCounts
true to add each pixel's event_counts (first 5 pixels on the page): the events it received, each split into browser (the pixel) and server (Conversions API). Answers "are my pixels firing?".
Clear enough to supply this argument.
eventCountDays
Days back for event_counts, 1-7 (Meta keeps seven). Defaults to 7.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_pixels",
"title": "List Meta pixels",
"description": "List the datasets/pixels on a Meta Ads account, for conversion-tracking context. Use when checking pixel inventory before diagnosing conversion tracking. Pass accountId (act_<digits> from meta_list_ad_accounts). To answer whether pixels are firing, pass includeEventCounts: each pixel gets the events it received over the last eventCountDays (1-7, default 7), each split into browser (the pixel) and server (Conversions API). Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"eventCountDays": {
"type": "integer",
"maximum": 7,
"minimum": 1,
"description": "Days back for event_counts, 1-7 (Meta keeps seven). Defaults to 7."
},
"includeEventCounts": {
"type": "boolean",
"description": "true to add each pixel's event_counts (first 5 pixels on the page): the events it received, each split into browser (the pixel) and server (Conversions API). Answers \"are my pixels firing?\"."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta pixels",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Lists custom and lookalike audiences saved in the connected Meta Ads account, including name, subtype, approximate size, and status. It does not return demographic or performance insights; use meta_insights with breakdowns for those.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Clear enough to supply this argument.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Clear enough to supply this argument.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_custom_audiences",
"title": "List Meta custom audiences",
"description": "Lists custom and lookalike audiences saved in the connected Meta Ads account, including name, subtype, approximate size, and status. It does not return demographic or performance insights; use meta_insights with breakdowns for those.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta custom audiences",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Search Meta's targeting taxonomy for interests, behaviors, demographics, and geo. Use for audience research — not to apply targeting (Meta Ads access is read-only). Pass accountId (act_<digits>) and query (the search term); optionally type (e.g. 'adinterest', 'adgeolocation') and limit. Get accountId by calling meta_list_ad_accounts first and using an id it returned — never invent or guess one, and never reuse an id from another platform. If meta_list_ad_accounts returns nothing, no Meta Ads account is connected: tell the user to connect one from the Ad Platforms page (Connect → Ad Platforms) rather than calling this tool.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Search term for interests, behaviors, demographics, or geo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
type
Targeting type filter (e.g. 'adinterest', 'adgeolocation', 'adbehavior').
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Max results, at most 100. Defaults to 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_search_targeting",
"title": "Search Meta targeting options",
"description": "Search Meta's targeting taxonomy for interests, behaviors, demographics, and geo. Use for audience research — not to apply targeting (Meta Ads access is read-only). Pass accountId (act_<digits>) and query (the search term); optionally type (e.g. 'adinterest', 'adgeolocation') and limit. Get accountId by calling meta_list_ad_accounts first and using an id it returned — never invent or guess one, and never reuse an id from another platform. If meta_list_ad_accounts returns nothing, no Meta Ads account is connected: tell the user to connect one from the Ad Platforms page (Connect → Ad Platforms) rather than calling this tool.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"query"
],
"properties": {
"type": {
"type": "string",
"minLength": 1,
"description": "Targeting type filter (e.g. 'adinterest', 'adgeolocation', 'adbehavior')."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Max results, at most 100. Defaults to 25."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Search term for interests, behaviors, demographics, or geo."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search Meta targeting options",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Get the product catalog id(s) this account actually advertises, derived from its ad sets (ads_read only — no business_management consent needed). This is the FALLBACK for finding a catalogId: prefer meta_list_catalogs (via the account's businessId from meta_get_object), and use this when the connection lacks business_management or you want to avoid that consent. Feeds the catalog tools (meta_list_catalog_products, meta_list_product_sets, meta_catalog_diagnostics, meta_list_feed_rules). Pass accountId (act_<digits> from meta_list_ad_accounts). Returns rows with productCatalogId, productSetId, and the referencing ad set. Returns empty when no live ad set references a catalog. Paginate with pageSize and nextPageToken. This reads the account's ad sets, which is heavy on large accounts — if the lookup fails, retry with a small pageSize or fall back to meta_list_catalogs via the businessId.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_resolve_catalogs",
"title": "Resolve Meta catalogs",
"description": "Get the product catalog id(s) this account actually advertises, derived from its ad sets (ads_read only — no business_management consent needed). This is the FALLBACK for finding a catalogId: prefer meta_list_catalogs (via the account's businessId from meta_get_object), and use this when the connection lacks business_management or you want to avoid that consent. Feeds the catalog tools (meta_list_catalog_products, meta_list_product_sets, meta_catalog_diagnostics, meta_list_feed_rules). Pass accountId (act_<digits> from meta_list_ad_accounts). Returns rows with productCatalogId, productSetId, and the referencing ad set. Returns empty when no live ad set references a catalog. Paginate with pageSize and nextPageToken. This reads the account's ad sets, which is heavy on large accounts — if the lookup fails, retry with a small pageSize or fall back to meta_list_catalogs via the businessId.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Resolve Meta catalogs",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
List the product catalogs owned by a business, for Advantage+ Shopping and commerce analysis. This is the primary way to find an account's catalogs: first get the owning businessId from meta_get_object on the account with fields ["business"] (needs the business_management permission), then pass it here. Pass accountId (act_<digits> from meta_list_ad_accounts) and businessId. Needs the catalog_management permission; if missingScopes is returned by either call, tell the user to reconnect to grant the listed permissions. If you can't use business_management, fall back to meta_resolve_catalogs, which derives the catalog id from the account's ads with no extra permission. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
businessId
The business id that owns the catalogs — read it from meta_get_object on the account, requesting the business field (needs the business_management permission). meta_resolve_catalogs is the no-business_management alternative.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Clear enough to supply this argument.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_catalogs",
"title": "List Meta catalogs",
"description": "List the product catalogs owned by a business, for Advantage+ Shopping and commerce analysis. This is the primary way to find an account's catalogs: first get the owning businessId from meta_get_object on the account with fields [\"business\"] (needs the business_management permission), then pass it here. Pass accountId (act_<digits> from meta_list_ad_accounts) and businessId. Needs the catalog_management permission; if missingScopes is returned by either call, tell the user to reconnect to grant the listed permissions. If you can't use business_management, fall back to meta_resolve_catalogs, which derives the catalog id from the account's ads with no extra permission. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"businessId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"businessId": {
"type": "string",
"minLength": 1,
"description": "The business id that owns the catalogs — read it from meta_get_object on the account, requesting the business field (needs the business_management permission). meta_resolve_catalogs is the no-business_management alternative."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta catalogs",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the products in a catalog, with availability, price, and status. Use to resolve a product_id to a product, or to find underperforming products for Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally a filter object. Needs catalog_management. Note: enumerating a catalog's products also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect; instead resolve product details one at a time with meta_get_product by id, and get per-product performance from meta_insights with breakdowns ["product_id"]. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
catalogId
The catalog id, from meta_list_catalogs (or meta_resolve_catalogs).
Clear enough to supply this argument.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › items › field
Product field to filter on, e.g. "availability".
Clear enough to supply this argument.
filters › items › operator
Comparison operator.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
filters › items › value
Value to compare against. Use an array with is_any / is_not_any.
Clear enough to supply this argument.
filtersCombine
How multiple filter conditions combine. Default and.
Clear enough to supply this argument.
pageSize
Rows per page. Defaults to the provider default.
Clear enough to supply this argument.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_catalog_products",
"title": "List Meta catalog products",
"description": "List the products in a catalog, with availability, price, and status. Use to resolve a product_id to a product, or to find underperforming products for Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally a filter object. Needs catalog_management. Note: enumerating a catalog's products also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect; instead resolve product details one at a time with meta_get_product by id, and get per-product performance from meta_insights with breakdowns [\"product_id\"]. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"catalogId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"operator",
"value"
],
"properties": {
"field": {
"type": "string",
"minLength": 1,
"description": "Product field to filter on, e.g. \"availability\"."
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
],
"description": "Value to compare against. Use an array with is_any / is_not_any."
},
"operator": {
"enum": [
"eq",
"neq",
"lt",
"lte",
"gt",
"gte",
"contains",
"i_contains",
"is_any",
"is_not_any"
],
"type": "string",
"description": "Comparison operator."
}
}
},
"minItems": 1,
"description": "Optional product filter conditions. Note: filtering disables the asset-level fallback path, so results come from the catalog node only."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"catalogId": {
"type": "string",
"minLength": 1,
"description": "The catalog id, from meta_list_catalogs (or meta_resolve_catalogs)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
},
"filtersCombine": {
"enum": [
"and",
"or"
],
"type": "string",
"description": "How multiple filter conditions combine. Default and."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta catalog products",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
List the product sets defined in a catalog (the groupings campaigns advertise). Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
catalogId
The catalog id, from meta_list_catalogs (or meta_resolve_catalogs).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_product_sets",
"title": "List Meta product sets",
"description": "List the product sets defined in a catalog (the groupings campaigns advertise). Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"catalogId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"catalogId": {
"type": "string",
"minLength": 1,
"description": "The catalog id, from meta_list_catalogs (or meta_resolve_catalogs)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta product sets",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Get a single catalog product by id — full fields including title, price, availability, and image. Use to resolve a product_id surfaced by an ad or product set to its details. Pass accountId (act_<digits> from meta_list_ad_accounts) and productId. Needs catalog_management; if missingScopes is returned, surface that the connection must grant it.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
productId
The product id (resolve from meta_list_catalog_products, or an ad's product set).
Clear enough to supply this argument.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get a Meta catalog product",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema33/100
Declare the result fields and their types in the output schema.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_get_product",
"title": "Get a Meta catalog product",
"description": "Get a single catalog product by id — full fields including title, price, availability, and image. Use to resolve a product_id surfaced by an ad or product set to its details. Pass accountId (act_<digits> from meta_list_ad_accounts) and productId. Needs catalog_management; if missingScopes is returned, surface that the connection must grant it.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"productId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"productId": {
"type": "string",
"minLength": 1,
"description": "The product id (resolve from meta_list_catalog_products, or an ad's product set)."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object",
"missingScopes"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a Meta catalog product",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Return a catalog's diagnostics — feed/product issues that block products from serving (disapprovals, missing fields, image problems). Use when products are not showing in Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management. Note: reading a catalog's diagnostics also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs80/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
catalogId
The catalog id, from meta_list_catalogs (or meta_resolve_catalogs).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
fields
Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_catalog_diagnostics",
"title": "Get Meta catalog diagnostics",
"description": "Return a catalog's diagnostics — feed/product issues that block products from serving (disapprovals, missing fields, image problems). Use when products are not showing in Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management. Note: reading a catalog's diagnostics also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"catalogId"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Optional list of fields to return. Defaults to a standard set. Meta silently ignores unsupported or misspelled field names and omits fields with no value — check droppedFields in the result for anything you asked for that did not come back."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"catalogId": {
"type": "string",
"minLength": 1,
"description": "The catalog id, from meta_list_catalogs (or meta_resolve_catalogs)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta catalog diagnostics",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
List the feed transformation rules applied to a catalog's product feeds. Use when investigating how feed data is being mapped or transformed. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally feedId to scope to one feed. Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The Meta ad account id in act_<digits> form, from meta_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
catalogId
The catalog id, from meta_list_catalogs (or meta_resolve_catalogs).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
feedId
Optional feed id to scope the rules to one product feed.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page. Defaults to the provider default.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
nextPageToken from a previous call, to read the next page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "meta_list_feed_rules",
"title": "List Meta feed rules",
"description": "List the feed transformation rules applied to a catalog's product feeds. Use when investigating how feed data is being mapped or transformed. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally feedId to scope to one feed. Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"catalogId"
],
"properties": {
"feedId": {
"type": "string",
"minLength": 1,
"description": "Optional feed id to scope the rules to one product feed."
},
"pageSize": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Rows per page. Defaults to the provider default."
},
"accountId": {
"type": "string",
"minLength": 1,
"description": "The Meta ad account id in act_<digits> form, from meta_list_ad_accounts."
},
"catalogId": {
"type": "string",
"minLength": 1,
"description": "The catalog id, from meta_list_catalogs (or meta_resolve_catalogs)."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "nextPageToken from a previous call, to read the next page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken",
"missingScopes"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"dateRange": {
"anyOf": [
{
"type": "object",
"required": [
"datePreset"
],
"properties": {
"datePreset": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"since",
"until"
],
"properties": {
"since": {
"type": "string"
},
"until": {
"type": "string"
}
},
"additionalProperties": false
}
],
"description": "Insights: the window the rows cover, as requested."
},
"emptyReason": {
"type": "string",
"description": "Set when nothing came back: why, in Meta's terms. Tell the user this reason; do not report the empty result as an error."
},
"droppedFields": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Fields you requested that came back with NO value on anything returned. Meta silently ignores unsupported or misspelled field names and omits fields without a value, so a listed field means UNREAD, not empty: tell the user you could not read it, and NEVER infer its content from other signals — an account's country, currency, or timezone says nothing about the language of its ad copy or message templates."
},
"missingScopes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Meta feed rules",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Return Meta's official advertising policy and compliance references (Advertising Standards, prohibited and restricted content, Special Ad Categories, commerce policies, community standards) with their canonical URLs and a short summary of each. Use when reviewing whether an ad, creative, or landing page is compliant, or when the user asks what Meta allows. Optionally pass topic to filter to a specific area (e.g. "restricted", "special ad categories"). This is curated reference data, not a live account lookup.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
topic
Optional topic filter (e.g. 'restricted', 'special ad categories'). Omit for all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "meta_get_policy",
"title": "Get Meta policy details",
"description": "Return Meta's official advertising policy and compliance references (Advertising Standards, prohibited and restricted content, Special Ad Categories, commerce policies, community standards) with their canonical URLs and a short summary of each. Use when reviewing whether an ad, creative, or landing page is compliant, or when the user asks what Meta allows. Optionally pass topic to filter to a specific area (e.g. \"restricted\", \"special ad categories\"). This is curated reference data, not a live account lookup.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"topic": {
"type": "string",
"minLength": 1,
"description": "Optional topic filter (e.g. 'restricted', 'special ad categories'). Omit for all."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"policies"
],
"properties": {
"policies": {
"type": "array",
"items": {
"type": "object",
"required": [
"topic",
"title",
"url",
"summary"
],
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"topic": {
"type": "string"
},
"summary": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta policy details",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Return definitions of the Meta Ads performance metrics produced by meta_insights — what each field means and its unit (spend, impressions, reach, frequency, clicks, link clicks, CTR, CPC, CPM, actions, action_values, purchase_roas, cost_per_action_type, video play milestones). Use to interpret meta_insights output correctly before drawing conclusions. Pass metric to get one definition (e.g. "purchase_roas"); omit it to get them all. This is curated reference data, not a live account lookup.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
metric
Optional metric name (e.g. 'purchase_roas'). Omit for all definitions.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "meta_get_metric_definition",
"title": "Get Meta metric definition",
"description": "Return definitions of the Meta Ads performance metrics produced by meta_insights — what each field means and its unit (spend, impressions, reach, frequency, clicks, link clicks, CTR, CPC, CPM, actions, action_values, purchase_roas, cost_per_action_type, video play milestones). Use to interpret meta_insights output correctly before drawing conclusions. Pass metric to get one definition (e.g. \"purchase_roas\"); omit it to get them all. This is curated reference data, not a live account lookup.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"metric": {
"type": "string",
"minLength": 1,
"description": "Optional metric name (e.g. 'purchase_roas'). Omit for all definitions."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"definitions"
],
"properties": {
"definitions": {
"type": "array",
"items": {
"type": "object",
"required": [
"metric",
"name",
"definition",
"unit"
],
"properties": {
"name": {
"type": "string"
},
"unit": {
"type": "string"
},
"metric": {
"type": "string"
},
"definition": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get Meta metric definition",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the Google Analytics accounts and GA4 properties this connection can access. Use this FIRST for any GA4 task to get a propertyId (properties/<digits>) to pass to the other google_analytics_ tools. Takes no arguments. Returns account summaries with their nested property summaries (property id, display name), as HYPD last synced them: a property added in Google since then appears after the user refreshes Google Analytics on the Ad Platforms page. If nothing is returned, no Google Analytics Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountSummaries"
],
"properties": {
"planNotice": {
"type": "string",
"description": "Explains properties held back by the user's plan."
},
"accountSummaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"account": {
"type": "string",
"description": "The account id, accounts/<digits>."
},
"displayName": {
"type": "string",
"description": "The account's name."
},
"propertySummaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"property": {
"type": "string",
"description": "The property id every report takes."
},
"displayName": {
"type": "string",
"description": "The property's name."
},
"propertyType": {
"type": "string",
"description": "e.g. PROPERTY_TYPE_ORDINARY."
}
},
"additionalProperties": {}
},
"description": "The account's GA4 properties."
}
},
"additionalProperties": {}
},
"description": "The user's selected GA4 accounts and their properties."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_analytics_list_account_summaries",
"title": "List Google Analytics accounts",
"description": "List the Google Analytics accounts and GA4 properties this connection can access. Use this FIRST for any GA4 task to get a propertyId (properties/<digits>) to pass to the other google_analytics_ tools. Takes no arguments. Returns account summaries with their nested property summaries (property id, display name), as HYPD last synced them: a property added in Google since then appears after the user refreshes Google Analytics on the Ad Platforms page. If nothing is returned, no Google Analytics Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountSummaries"
],
"properties": {
"planNotice": {
"type": "string",
"description": "Explains properties held back by the user's plan."
},
"accountSummaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"account": {
"type": "string",
"description": "The account id, accounts/<digits>."
},
"displayName": {
"type": "string",
"description": "The account's name."
},
"propertySummaries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"property": {
"type": "string",
"description": "The property id every report takes."
},
"displayName": {
"type": "string",
"description": "The property's name."
},
"propertyType": {
"type": "string",
"description": "e.g. PROPERTY_TYPE_ORDINARY."
}
},
"additionalProperties": {}
},
"description": "The account's GA4 properties."
}
},
"additionalProperties": {}
},
"description": "The user's selected GA4 accounts and their properties."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Google Analytics accounts",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description90/100
Get a GA4 property's metadata — display name, timezone, currency, and industry category. Use to orient before reporting (the timezone and currency frame every metric). Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
List the Google Ads links on a GA4 property — confirm whether GA4 is linked to Google Ads (required for campaign-level joins and imported conversions). Use before google_analytics_get_campaign_performance when Google Ads dimensions look empty. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries). If a rate-limit error is returned, run Google Analytics calls sequentially instead of in parallel and retry after the indicated wait.
Describe the returned information so the agent knows whether it will answer the request.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"guidance": {
"type": "string",
"description": "What to tell the user when nothing is connected."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Analytics connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_analytics_list_google_ads_links",
"title": "List Analytics → Google Ads links",
"description": "List the Google Ads links on a GA4 property — confirm whether GA4 is linked to Google Ads (required for campaign-level joins and imported conversions). Use before google_analytics_get_campaign_performance when Google Ads dimensions look empty. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries). If a rate-limit error is returned, run Google Analytics calls sequentially instead of in parallel and retry after the indicated wait.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"propertyId"
],
"properties": {
"propertyId": {
"type": "string",
"minLength": 1,
"description": "The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"guidance": {
"type": "string",
"description": "What to tell the user when nothing is connected."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Analytics connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Analytics → Google Ads links",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
Describe the Google Analytics connection — the data source, the granted scope (read-only), and how properties are addressed (pass a propertyId per call; discover them with google_analytics_list_account_summaries). Use when the user asks what you're connected to or what you can access. Takes no arguments.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
{
"name": "google_analytics_describe_server",
"title": "Describe Analytics data access",
"description": "Describe the Google Analytics connection — the data source, the granted scope (read-only), and how properties are addressed (pass a propertyId per call; discover them with google_analytics_list_account_summaries). Use when the user asks what you're connected to or what you can access. Takes no arguments.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"source",
"scope",
"propertyModel",
"note"
],
"properties": {
"note": {
"type": "string"
},
"scope": {
"type": "string"
},
"source": {
"type": "string"
},
"propertyModel": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Describe Analytics data access",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Pre-flight a report's size with a one-row GA4 report request that consumes Data API quota. Returns the unpaged row count and property quota state, without returning report rows. Use before google_analytics_run_report to size a broad query before a full fetch. Pass propertyId, metrics, dateRanges, and optionally dimensions and filters. GA4 hard limits: at most 4 dateRanges, 10 metrics, and 9 dimensions per request.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
metrics
GA4 metric API names, e.g. sessions, conversions, totalRevenue.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Clear enough to supply this argument.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Clear enough to supply this argument.
dimensions
GA4 dimension API names, e.g. sessionDefaultChannelGroup.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description80/100
The open-ended GA4 report: any dimensions x metrics x date range, with optional filters, ordering, and paging (limit/offset). Use for ad-hoc questions the preset performance tools do not cover. Validate combos with google_analytics_check_compatibility and size with google_analytics_estimate_report_rows first. Pass propertyId, metrics, dateRanges, and optionally dimensions, dimensionFilter/metricFilter (a single condition on a field, or an andGroup/orGroup of conditions), orderBys, limit, offset. GA4 hard limits: at most 4 dateRanges, 10 metrics, and 9 dimensions per request. If a rate-limit error is returned, run Google Analytics calls sequentially instead of in parallel and retry after the indicated wait.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
metrics
GA4 metric API names, e.g. sessions, conversions, totalRevenue.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Clear enough to supply this argument.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Clear enough to supply this argument.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Clear enough to supply this argument.
dimensions
GA4 dimension API names, e.g. sessionDefaultChannelGroup.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Recent activity from the GA4 Realtime API — active users and events over the last 30 minutes by default, or the supplied minuteRanges. Use for "what's happening now" checks, not historical analysis (use google_analytics_run_report for that). The Realtime API accepts only its own small field set — dimensions like unifiedScreenName, country, city, deviceCategory, platform, appVersion, audienceName, eventName, and metrics like activeUsers, screenPageViews, eventCount, keyEvents. Core-report fields (e.g. sessionSource, sessionDefaultChannelGroup, unifiedScreenClass, sessions, totalRevenue) are not valid here and will be rejected. Pass propertyId and metrics; optionally dimensions, minuteRanges, filters, and limit.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
metrics
GA4 realtime metric API names (1-10), e.g. activeUsers, screenPageViews, eventCount, keyEvents. Standard report metrics such as sessions and totalRevenue are not valid here.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensions
GA4 REALTIME dimension API names (at most 4). The Realtime API has its own small dimension set — e.g. unifiedScreenName, country, deviceCategory, platform, audienceName, eventName. Core-report dimensions like sessionSource or unifiedScreenClass are rejected here.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
minuteRanges › items › startMinutesAgo
Range start, minutes before now (0 = now).
Clear enough to supply this argument.
minuteRanges › items › endMinutesAgo
Where the range ends, in minutes before now. 0, Google's default, ends at the current minute.
Clear enough to supply this argument.
minuteRanges › items › name
Optional label echoed on the range's rows.
Clear enough to supply this argument.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Funnel / drop-off analysis (GA4 Data API v1alpha) — step-by-step completion and abandonment for a sequence of events or conditions. Use for "where do users drop off" questions. Pass propertyId, dateRanges, and a funnel: an ordered steps array where each step has a name and a filterExpression (an event or field condition). Optionally funnelBreakdown (breakdownDimension.name — a GA4 dimension API name — plus an optional limit of at most 15) and limit.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Clear enough to supply this argument.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Clear enough to supply this argument.
funnel › steps › items › name
Step label shown in the report.
Clear enough to supply this argument.
funnel › steps › items › isDirectlyFollowedBy
When true, this step must directly follow the previous one.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Report conversions, total revenue, and sessions grouped by sessionDefaultChannelGroup and sessionCampaignName, ordered by conversions descending. Use to compare conversion outcomes across session channels and campaigns. Aggregate rows only; it does not return multi-step conversion paths or assisted-conversion credit. Pass propertyId and dateRanges; optionally a dimensionFilter and limit.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Clear enough to supply this argument.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Report conversions, total revenue, and sessions grouped jointly by firstUserDefaultChannelGroup and sessionDefaultChannelGroup, ordered by conversions descending. Use to examine first-user acquisition channels alongside session acquisition channels. This preset does not compare attribution models or calculate changes in conversion credit. Pass propertyId and dateRanges; optionally a dimensionFilter and limit.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Report sessions, total users, conversions, total revenue, and average session duration by sessionCampaignName and sessionSourceMedium, ordered by sessions descending. Use to evaluate acquisition campaign outcomes in GA4; filter to paid traffic when needed. This preset does not return ad spend or ROAS, or join Google Ads campaign records. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Clear enough to supply this argument.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Report sessions, total users, engagement rate, average session duration, conversions, and total revenue by landingPagePlusQueryString, ordered by sessions descending. Use to evaluate entry pages, including their query strings, for landing-page and post-click quality questions. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Clear enough to supply this argument.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Report items viewed, items added to cart, items purchased, and item revenue by itemName, ordered by item revenue descending. Use to compare product engagement and sales. This preset does not group by source or campaign or return transaction counts. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dateRanges › items › startDate
Start date: YYYY-MM-DD or a relative date like 28daysAgo.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › endDate
End date: YYYY-MM-DD or a relative date like today.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dateRanges › items › name
A label for this range. With several ranges, rows carry it in the dateRange dimension.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
List the dimensions and metrics available for a GA4 property (the GA4 Data API metadata), including custom ones. Use to discover valid API names before building a google_analytics_run_report query. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Declare the result fields and their types in the output schema.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"guidance": {
"type": "string",
"description": "What to tell the user when nothing is connected."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Analytics connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_analytics_get_metadata",
"title": "List Analytics dimensions and metrics",
"description": "List the dimensions and metrics available for a GA4 property (the GA4 Data API metadata), including custom ones. Use to discover valid API names before building a google_analytics_run_report query. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"propertyId"
],
"properties": {
"propertyId": {
"type": "string",
"minLength": 1,
"description": "The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"guidance": {
"type": "string",
"description": "What to tell the user when nothing is connected."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Analytics connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Analytics dimensions and metrics",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
List a property's custom dimensions and custom metrics (the Admin API definitions) — the property-specific fields beyond the GA4 standard set. Use to find a client's custom field API names before reporting on them. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Validate that a set of GA4 dimensions and metrics can be queried together before running a report (GA4 rejects incompatible combos). Use to de-risk a google_analytics_run_report query the user is unsure about. Pass propertyId and the dimensions/metrics to test; optionally a compatibilityFilter (COMPATIBLE or INCOMPATIBLE). An incompatible combination is a normal answer, not an error: the tool returns compatible: false with GA4's reason.
The description explains the capability, when to use it, and what to expect.
Inputs85/100
106 of 108 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
propertyId
The GA4 Property ID in properties/<digits> form, from google_analytics_list_account_summaries.
Clear enough to supply this argument.
dimensions
Not provided
Missing description. Explain what this value means and how to supply it.
metrics
Not provided
Missing description. Explain what this value means and how to supply it.
dimensionFilter › filter › fieldName
The GA4 dimension or metric API name to filter on.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the Search Console properties (sites) this connection can access. Use this FIRST for any Search Console task to get the siteUrl to pass to the other search_console_ tools — copy it EXACTLY as returned ('sc-domain:example.com' is a domain property, 'https://example.com/' a URL-prefix property; never rewrite one form into the other). Takes no arguments. Returns each site with its permission level, as HYPD last synced them: a site added in Google since then appears after the user refreshes Google Search Console on the Ad Platforms page. If nothing is returned, no Google Search Console Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sites"
],
"properties": {
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"siteUrl": {
"type": "string",
"description": "The property identity to pass as siteUrl, verbatim."
},
"permissionLevel": {
"type": "string",
"description": "The user's access, e.g. siteOwner or siteFullUser."
}
},
"additionalProperties": {}
},
"description": "Properties the user selected for HYPD, by siteUrl."
},
"planNotice": {
"type": "string",
"description": "Explains properties held back by the user's plan."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_list_sites",
"title": "List Search Console sites",
"description": "List the Search Console properties (sites) this connection can access. Use this FIRST for any Search Console task to get the siteUrl to pass to the other search_console_ tools — copy it EXACTLY as returned ('sc-domain:example.com' is a domain property, 'https://example.com/' a URL-prefix property; never rewrite one form into the other). Takes no arguments. Returns each site with its permission level, as HYPD last synced them: a site added in Google since then appears after the user refreshes Google Search Console on the Ad Platforms page. If nothing is returned, no Google Search Console Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sites"
],
"properties": {
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"siteUrl": {
"type": "string",
"description": "The property identity to pass as siteUrl, verbatim."
},
"permissionLevel": {
"type": "string",
"description": "The user's access, e.g. siteOwner or siteFullUser."
}
},
"additionalProperties": {}
},
"description": "Properties the user selected for HYPD, by siteUrl."
},
"planNotice": {
"type": "string",
"description": "Explains properties held back by the user's plan."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Search Console sites",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
Shorten the title to an action and subject; move usage details into the description.
Description97/100
Organic performance for a connected site: clicks, impressions, CTR and average position, grouped by up to two dimensions with filters. Position is an impression-weighted average; filter position bands after fetching. Avoid page+query grouping (load-quota risk); use search_console_page_query_breakdown. Dates default to 28 days ending 3 days ago. dataState defaults to final; use all only when the user compares with their live Search Console dashboard, and flag recent data as provisional. Check the echoed executed query, dates and estimatedDataFinalizedThrough; dimensions [] means no grouping. rowLimit defaults to 250, max 25000; page with startRow. truncated and rowCount signal incomplete results. Keep one searchType; CTR baselines differ across web/image. Rare query rows are withheld and do not sum to site totals. Copy siteUrl from search_console_list_sites.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
siteUrl
The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other.
Clear enough to supply this argument.
startDate
Start of the date range, within Search Console's 16-month retention. Defaults to a 28-day window ending 3 days ago, where finalized data ends.
Clear enough to supply this argument.
endDate
End of the date range. Defaults to 3 days ago, where finalized data ends.
Clear enough to supply this argument.
dimensions
Row grouping. Do NOT group page and query together — that is the load-quota trap; use search_console_page_query_breakdown instead.
Clear enough to supply this argument.
searchType
Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines.
Clear enough to supply this argument.
dataState
Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used.
Clear enough to supply this argument.
rowLimit
The most rows to return on this call. The response's truncated says whether more exist; page with startRow for them.
Clear enough to supply this argument.
startRow
Zero-based index of the first row. For the next page, repeat the query with startRow plus the previous rowCount.
Clear enough to supply this argument.
filters › items › dimension
The row field this filter tests.
Clear enough to supply this argument.
filters › items › operator
How expression is matched: exact value, substring, or an RE2 regular expression.
Clear enough to supply this argument.
filters › items › expression
The value to match: a query or URL fragment, a lowercase ISO 3166-1 alpha-3 country such as 'usa', or a device: DESKTOP, MOBILE or TABLET.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per requested dimension, in request order. Absent for an ungrouped total."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Average position of the topmost result, 1 is first."
},
"impressions": {
"type": "number",
"description": "Times a result was shown in Google Search."
}
},
"additionalProperties": {}
},
"description": "Metrics per dimension combination."
},
"query": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The query as executed, defaults filled in.",
"additionalProperties": false
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows returned on this call."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"truncated": {
"type": "boolean",
"description": "True when the site had more rows than rowLimit returned — treat the data as INCOMPLETE and say so; raise rowLimit or page with startRow to see the rest."
},
"loadQuotaWarning": {
"type": "string",
"description": "Present when the query grouped page and query together — the load-quota trap. The data is real; the shape is what to avoid."
},
"anonymizedQueriesNote": {
"type": "string",
"description": "Explains why query rows don't sum to site totals."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_query_search_analytics",
"title": "Query search analytics",
"description": "Organic performance for a connected site: clicks, impressions, CTR and average position, grouped by up to two dimensions with filters. Position is an impression-weighted average; filter position bands after fetching. Avoid page+query grouping (load-quota risk); use search_console_page_query_breakdown. Dates default to 28 days ending 3 days ago. dataState defaults to final; use all only when the user compares with their live Search Console dashboard, and flag recent data as provisional. Check the echoed executed query, dates and estimatedDataFinalizedThrough; dimensions [] means no grouping. rowLimit defaults to 250, max 25000; page with startRow. truncated and rowCount signal incomplete results. Keep one searchType; CTR baselines differ across web/image. Rare query rows are withheld and do not sum to site totals. Copy siteUrl from search_console_list_sites.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"siteUrl"
],
"properties": {
"endDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "End of the date range. Defaults to 3 days ago, where finalized data ends."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"enum": [
"equals",
"notEquals",
"contains",
"notContains",
"includingRegex",
"excludingRegex"
],
"type": "string",
"description": "How expression is matched: exact value, substring, or an RE2 regular expression."
},
"dimension": {
"enum": [
"query",
"page",
"country",
"device",
"searchAppearance"
],
"type": "string",
"description": "The row field this filter tests."
},
"expression": {
"type": "string",
"minLength": 1,
"description": "The value to match: a query or URL fragment, a lowercase ISO 3166-1 alpha-3 country such as 'usa', or a device: DESKTOP, MOBILE or TABLET."
}
}
},
"maxItems": 4,
"description": "Row filters, ANDed together (e.g. country equals 'usa', page contains '/blog/')."
},
"siteUrl": {
"type": "string",
"minLength": 1,
"description": "The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other."
},
"rowLimit": {
"type": "integer",
"default": 250,
"maximum": 25000,
"minimum": 1,
"description": "The most rows to return on this call. The response's truncated says whether more exist; page with startRow for them."
},
"startRow": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based index of the first row. For the next page, repeat the query with startRow plus the previous rowCount."
},
"dataState": {
"enum": [
"final",
"all"
],
"type": "string",
"default": "final",
"description": "Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used."
},
"startDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Start of the date range, within Search Console's 16-month retention. Defaults to a 28-day window ending 3 days ago, where finalized data ends."
},
"dimensions": {
"type": "array",
"items": {
"enum": [
"query",
"page",
"country",
"device",
"date",
"searchAppearance"
],
"type": "string"
},
"maxItems": 2,
"description": "Row grouping. Do NOT group page and query together — that is the load-quota trap; use search_console_page_query_breakdown instead."
},
"searchType": {
"enum": [
"web",
"image",
"video",
"news",
"discover",
"googleNews"
],
"type": "string",
"default": "web",
"description": "Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per requested dimension, in request order. Absent for an ungrouped total."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Average position of the topmost result, 1 is first."
},
"impressions": {
"type": "number",
"description": "Times a result was shown in Google Search."
}
},
"additionalProperties": {}
},
"description": "Metrics per dimension combination."
},
"query": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The query as executed, defaults filled in.",
"additionalProperties": false
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows returned on this call."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"truncated": {
"type": "boolean",
"description": "True when the site had more rows than rowLimit returned — treat the data as INCOMPLETE and say so; raise rowLimit or page with startRow to see the rest."
},
"loadQuotaWarning": {
"type": "string",
"description": "Present when the query grouped page and query together — the load-quota trap. The data is real; the shape is what to avoid."
},
"anonymizedQueriesNote": {
"type": "string",
"description": "Explains why query rows don't sum to site totals."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Query search analytics",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Compare Search Analytics between two periods with correct date math: pass the current period, and the previous one defaults to the immediately preceding window of equal length. Returns one row per dimension key (default: page) with current, previous, and delta metrics — the tool for "traffic dropped this week: when did it start and which pages and queries carry the loss?". Both periods are echoed back with the dimensions and rowLimit executed and estimatedDataFinalizedThrough; keep dataState 'final' (the default) or a fresh-but-unfinalized current period will show a drop that never happened. currentTruncated / previousTruncated flag a clipped period — a row missing from a clipped side reads as appeared or disappeared, so raise rowLimit before trusting appearance/disappearance findings. Position deltas compare impression-weighted averages, not ranks.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
siteUrl
The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other.
Clear enough to supply this argument.
currentStartDate
Start of the current period, the one being explained.
Clear enough to supply this argument.
currentEndDate
End of the current period.
Clear enough to supply this argument.
previousStartDate
Start of the comparison period. Defaults to the immediately preceding window of equal length.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
previousEndDate
End of the comparison period. Pass it with previousStartDate, or neither for the default window.
Clear enough to supply this argument.
dimensions
Row grouping to compare by. Defaults to page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
searchType
Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines.
Clear enough to supply this argument.
dataState
Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used.
Clear enough to supply this argument.
rowLimit
The most rows to return on this call. The response's truncated says whether more exist.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"keys",
"current",
"previous",
"delta"
],
"properties": {
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per dimension, in request order."
},
"delta": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "current minus previous; null unless both exist."
},
"current": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current period; null when the row is absent there."
},
"previous": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Previous period; null when the row is absent there."
}
},
"additionalProperties": false
},
"description": "One row per dimension combination seen in either period."
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"currentPeriod": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The current query as executed.",
"additionalProperties": false
},
"previousPeriod": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The previous query as executed.",
"additionalProperties": false
},
"currentTruncated": {
"type": "boolean",
"description": "True when the current period had more rows than rowLimit — rows missing from a clipped period read as appeared/disappeared, so treat the comparison as incomplete."
},
"previousTruncated": {
"type": "boolean",
"description": "True when the previous period had more rows than rowLimit — same caveat as currentTruncated: a clipped previous period fakes newly-appeared rows."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_compare_periods",
"title": "Compare search performance periods",
"description": "Compare Search Analytics between two periods with correct date math: pass the current period, and the previous one defaults to the immediately preceding window of equal length. Returns one row per dimension key (default: page) with current, previous, and delta metrics — the tool for \"traffic dropped this week: when did it start and which pages and queries carry the loss?\". Both periods are echoed back with the dimensions and rowLimit executed and estimatedDataFinalizedThrough; keep dataState 'final' (the default) or a fresh-but-unfinalized current period will show a drop that never happened. currentTruncated / previousTruncated flag a clipped period — a row missing from a clipped side reads as appeared or disappeared, so raise rowLimit before trusting appearance/disappearance findings. Position deltas compare impression-weighted averages, not ranks.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"siteUrl",
"currentStartDate",
"currentEndDate"
],
"properties": {
"siteUrl": {
"type": "string",
"minLength": 1,
"description": "The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other."
},
"rowLimit": {
"type": "integer",
"default": 250,
"maximum": 25000,
"minimum": 1,
"description": "The most rows to return on this call. The response's truncated says whether more exist."
},
"dataState": {
"enum": [
"final",
"all"
],
"type": "string",
"default": "final",
"description": "Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used."
},
"dimensions": {
"type": "array",
"items": {
"enum": [
"query",
"page",
"country",
"device"
],
"type": "string"
},
"maxItems": 2,
"description": "Row grouping to compare by. Defaults to page."
},
"searchType": {
"enum": [
"web",
"image",
"video",
"news",
"discover",
"googleNews"
],
"type": "string",
"default": "web",
"description": "Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines."
},
"currentEndDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "End of the current period."
},
"previousEndDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "End of the comparison period. Pass it with previousStartDate, or neither for the default window."
},
"currentStartDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Start of the current period, the one being explained."
},
"previousStartDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Start of the comparison period. Defaults to the immediately preceding window of equal length."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"required": [
"keys",
"current",
"previous",
"delta"
],
"properties": {
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per dimension, in request order."
},
"delta": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "current minus previous; null unless both exist."
},
"current": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current period; null when the row is absent there."
},
"previous": {
"anyOf": [
{
"type": "object",
"required": [
"clicks",
"impressions",
"ctr",
"position"
],
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Impression-weighted AVERAGE position across the row's impressions, not a rank. There is no position filter in the API — filter fetched rows yourself for position-band analyses (e.g. striking distance 8-15)."
},
"impressions": {
"type": "number",
"description": "Times a result was shown."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Previous period; null when the row is absent there."
}
},
"additionalProperties": false
},
"description": "One row per dimension combination seen in either period."
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"currentPeriod": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The current query as executed.",
"additionalProperties": false
},
"previousPeriod": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The previous query as executed.",
"additionalProperties": false
},
"currentTruncated": {
"type": "boolean",
"description": "True when the current period had more rows than rowLimit — rows missing from a clipped period read as appeared/disappeared, so treat the comparison as incomplete."
},
"previousTruncated": {
"type": "boolean",
"description": "True when the previous period had more rows than rowLimit — same caveat as currentTruncated: a clipped previous period fakes newly-appeared rows."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Compare search performance periods",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
The page-and-query view, done safely: pass a page URL to get the queries driving traffic to it, or a query to get the pages it lands on (exactly one of the two). This is the shape for cannibalisation checks (which pages compete for one query) and title/meta rewrites (which queries a page gets impressions for) — it uses a filter instead of grouping page and query together, which would trip Google's load quota. Rows carry clicks, impressions, CTR, and position (an impression-weighted average, not a rank); the response sets truncated with rowCount when more rows existed. For a page, rare queries are anonymised and withheld, so its query rows never sum to the page's totals.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
siteUrl
The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other.
Clear enough to supply this argument.
page
A page URL: returns the queries driving traffic to it. Pass exactly one of page or query.
Clear enough to supply this argument.
query
A search query: returns the pages it lands on. Pass exactly one of page or query.
Clear enough to supply this argument.
startDate
Start of the date range, within Search Console's 16-month retention. Defaults to a 28-day window ending 3 days ago, where finalized data ends.
Clear enough to supply this argument.
endDate
End of the date range. Defaults to 3 days ago, where finalized data ends.
Clear enough to supply this argument.
searchType
Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines.
Clear enough to supply this argument.
dataState
Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used.
Clear enough to supply this argument.
rowLimit
The most rows to return on this call. The response's truncated says whether more exist.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Break down pages by query",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema71/100
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per requested dimension, in request order. Absent for an ungrouped total."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Average position of the topmost result, 1 is first."
},
"impressions": {
"type": "number",
"description": "Times a result was shown in Google Search."
}
},
"additionalProperties": {}
},
"description": "Metrics per dimension combination."
},
"query": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The query as executed, defaults filled in.",
"additionalProperties": false
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows returned on this call."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"truncated": {
"type": "boolean",
"description": "True when the site had more rows than rowLimit returned — treat the data as INCOMPLETE and say so; raise rowLimit or page with startRow to see the rest."
},
"loadQuotaWarning": {
"type": "string",
"description": "Present when the query grouped page and query together — the load-quota trap. The data is real; the shape is what to avoid."
},
"anonymizedQueriesNote": {
"type": "string",
"description": "Explains why query rows don't sum to site totals."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_page_query_breakdown",
"title": "Break down pages by query",
"description": "The page-and-query view, done safely: pass a page URL to get the queries driving traffic to it, or a query to get the pages it lands on (exactly one of the two). This is the shape for cannibalisation checks (which pages compete for one query) and title/meta rewrites (which queries a page gets impressions for) — it uses a filter instead of grouping page and query together, which would trip Google's load quota. Rows carry clicks, impressions, CTR, and position (an impression-weighted average, not a rank); the response sets truncated with rowCount when more rows existed. For a page, rare queries are anonymised and withheld, so its query rows never sum to the page's totals.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"siteUrl"
],
"properties": {
"page": {
"type": "string",
"minLength": 1,
"description": "A page URL: returns the queries driving traffic to it. Pass exactly one of page or query."
},
"query": {
"type": "string",
"minLength": 1,
"description": "A search query: returns the pages it lands on. Pass exactly one of page or query."
},
"endDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "End of the date range. Defaults to 3 days ago, where finalized data ends."
},
"siteUrl": {
"type": "string",
"minLength": 1,
"description": "The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other."
},
"rowLimit": {
"type": "integer",
"default": 250,
"maximum": 25000,
"minimum": 1,
"description": "The most rows to return on this call. The response's truncated says whether more exist."
},
"dataState": {
"enum": [
"final",
"all"
],
"type": "string",
"default": "final",
"description": "Which days count. 'final' covers only days Google has finalized, which lag 2-3 days. 'all' adds the latest days, matching the live Search Console dashboard, whose numbers can still change. The response echoes which state and dates were used."
},
"startDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Start of the date range, within Search Console's 16-month retention. Defaults to a 28-day window ending 3 days ago, where finalized data ends."
},
"searchType": {
"enum": [
"web",
"image",
"video",
"news",
"discover",
"googleNews"
],
"type": "string",
"default": "web",
"description": "Search surface. Keep analyses on ONE surface: image CTR runs ~5-6x lower than web at the same position, so mixing surfaces corrupts CTR baselines."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ctr": {
"type": "number",
"description": "Click-through rate, from 0 to 1."
},
"keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "One value per requested dimension, in request order. Absent for an ungrouped total."
},
"clicks": {
"type": "number",
"description": "Clicks from Google Search."
},
"position": {
"type": "number",
"description": "Average position of the topmost result, 1 is first."
},
"impressions": {
"type": "number",
"description": "Times a result was shown in Google Search."
}
},
"additionalProperties": {}
},
"description": "Metrics per dimension combination."
},
"query": {
"type": "object",
"required": [
"startDate",
"endDate",
"searchType",
"dataState",
"dimensions",
"rowLimit",
"estimatedDataFinalizedThrough"
],
"properties": {
"endDate": {
"type": "string",
"description": "Last day queried."
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"type": "string",
"description": "How expression was matched."
},
"dimension": {
"type": "string",
"description": "The row field tested."
},
"expression": {
"type": "string",
"description": "The value matched."
}
},
"additionalProperties": false
},
"description": "The filters applied, ANDed together."
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Rows requested."
},
"startRow": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Index of the first row returned."
},
"dataState": {
"type": "string",
"description": "'final' or 'all'; 'all' rows can still change."
},
"startDate": {
"type": "string",
"description": "First day queried."
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row grouping actually applied. [] means NO grouping was applied and rows hold one site-wide aggregate — if you asked for a breakdown and see [], your dimensions argument did not arrive (check its spelling)."
},
"searchType": {
"type": "string",
"description": "Search surface queried."
},
"estimatedDataFinalizedThrough": {
"type": "string",
"description": "Estimated last day Google has finalized (~3 days behind today; Google exposes no exact value). Rows after this date are provisional and can change retroactively when dataState is 'all'."
}
},
"description": "The query as executed, defaults filled in.",
"additionalProperties": false
},
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows returned on this call."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"truncated": {
"type": "boolean",
"description": "True when the site had more rows than rowLimit returned — treat the data as INCOMPLETE and say so; raise rowLimit or page with startRow to see the rest."
},
"loadQuotaWarning": {
"type": "string",
"description": "Present when the query grouped page and query together — the load-quota trap. The data is real; the shape is what to avoid."
},
"anonymizedQueriesNote": {
"type": "string",
"description": "Explains why query rows don't sum to site totals."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Break down pages by query",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
List a site's submitted sitemaps with their status: last submitted and downloaded times, pending state, and per-content-type warning and error counts. Use it for indexing hygiene — a paid landing page missing from every sitemap or a sitemap with errors is a common reason pages don't index. Takes the siteUrl exactly as search_console_list_sites returned it.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
siteUrl
The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"sitemaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The sitemap's URL."
},
"type": {
"type": "string",
"description": "sitemap, rssFeed, atomFeed, urlList or notSitemap."
},
"errors": {
"type": "string",
"description": "Processing errors, a count as a decimal string."
},
"contents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Content type, e.g. web, image or video."
},
"indexed": {
"type": "string",
"description": "Google no longer fills this and returns '0' whatever the index state. Not an index count: inspect URLs one by one instead."
},
"submitted": {
"type": "string",
"description": "URLs submitted, a count as a decimal string."
}
},
"additionalProperties": {}
},
"description": "URL counts per content type."
},
"warnings": {
"type": "string",
"description": "Processing warnings, a count as a decimal string."
},
"isPending": {
"type": "boolean",
"description": "true while Google has yet to process it."
},
"lastSubmitted": {
"type": "string",
"description": "When it was last submitted (ISO 8601)."
},
"lastDownloaded": {
"type": "string",
"description": "When Google last fetched it (ISO 8601)."
},
"isSitemapsIndex": {
"type": "boolean",
"description": "true for a sitemap index that lists other sitemaps."
}
},
"additionalProperties": {}
},
"description": "Every sitemap Google knows for the property."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_list_sitemaps",
"title": "List sitemaps",
"description": "List a site's submitted sitemaps with their status: last submitted and downloaded times, pending state, and per-content-type warning and error counts. Use it for indexing hygiene — a paid landing page missing from every sitemap or a sitemap with errors is a common reason pages don't index. Takes the siteUrl exactly as search_console_list_sites returned it.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"siteUrl"
],
"properties": {
"siteUrl": {
"type": "string",
"minLength": 1,
"description": "The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"sitemaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The sitemap's URL."
},
"type": {
"type": "string",
"description": "sitemap, rssFeed, atomFeed, urlList or notSitemap."
},
"errors": {
"type": "string",
"description": "Processing errors, a count as a decimal string."
},
"contents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Content type, e.g. web, image or video."
},
"indexed": {
"type": "string",
"description": "Google no longer fills this and returns '0' whatever the index state. Not an index count: inspect URLs one by one instead."
},
"submitted": {
"type": "string",
"description": "URLs submitted, a count as a decimal string."
}
},
"additionalProperties": {}
},
"description": "URL counts per content type."
},
"warnings": {
"type": "string",
"description": "Processing warnings, a count as a decimal string."
},
"isPending": {
"type": "boolean",
"description": "true while Google has yet to process it."
},
"lastSubmitted": {
"type": "string",
"description": "When it was last submitted (ISO 8601)."
},
"lastDownloaded": {
"type": "string",
"description": "When Google last fetched it (ISO 8601)."
},
"isSitemapsIndex": {
"type": "boolean",
"description": "true for a sitemap index that lists other sitemaps."
}
},
"additionalProperties": {}
},
"description": "Every sitemap Google knows for the property."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List sitemaps",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Inspect one URL's status in Google's index: verdict, coverage state, Google-selected vs user-declared canonical, last crawl, referring sitemaps, and mobile/rich-result checks. THE tool for "is this landing page even indexed, and if not why?". The URL must belong to the siteUrl property. For several URLs, call this tool once per URL in parallel — there is no batch variant and the per-site quota is roomy (600 QPM).
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
siteUrl
The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other.
Clear enough to supply this argument.
inspectionUrl
The fully-qualified URL to inspect. Must belong to the siteUrl property.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
languageCode
BCP-47 language for result messages, e.g. en-US.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Inspect a URL's index status",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema82/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"inspectionResult": {
"type": "object",
"properties": {
"ampResult": {
"type": "object",
"properties": {
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
}
},
"description": "AMP status, present for AMP pages only.",
"additionalProperties": {}
},
"indexStatusResult": {
"type": "object",
"properties": {
"sitemap": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sitemaps that list this URL."
},
"verdict": {
"type": "string",
"description": "PASS when indexed, NEUTRAL when excluded, FAIL or PARTIAL on errors."
},
"crawledAs": {
"type": "string",
"description": "The crawler used: DESKTOP or MOBILE."
},
"coverageState": {
"type": "string",
"description": "Google's reason, e.g. 'Submitted and indexed' or 'Crawled - currently not indexed'."
},
"indexingState": {
"type": "string",
"description": "Whether a noindex blocks indexing, e.g. INDEXING_ALLOWED or BLOCKED_BY_META_TAG."
},
"lastCrawlTime": {
"type": "string",
"description": "When Google last crawled the URL (ISO 8601)."
},
"referringUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Pages Google found linking to this URL."
},
"userCanonical": {
"type": "string",
"description": "The canonical URL the page declares."
},
"pageFetchState": {
"type": "string",
"description": "Outcome of the last fetch, e.g. SUCCESSFUL, NOT_FOUND or SERVER_ERROR."
},
"robotsTxtState": {
"type": "string",
"description": "Whether robots.txt allows the crawl: ALLOWED or DISALLOWED."
},
"googleCanonical": {
"type": "string",
"description": "The canonical URL Google chose."
}
},
"description": "Whether the URL is indexed, and why or why not.",
"additionalProperties": {}
},
"richResultsResult": {
"type": "object",
"properties": {
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
},
"detectedItems": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"description": "Rich result types found on the page, with their issues."
}
},
"description": "Structured data Google detected for rich results.",
"additionalProperties": {}
},
"inspectionResultLink": {
"type": "string",
"description": "This inspection in the Search Console UI."
},
"mobileUsabilityResult": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
}
},
"description": "Mobile usability. Google retired the report, so VERDICT_UNSPECIFIED is common.",
"additionalProperties": {}
}
},
"description": "Google's URL Inspection result for the URL.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_inspect_url",
"title": "Inspect a URL's index status",
"description": "Inspect one URL's status in Google's index: verdict, coverage state, Google-selected vs user-declared canonical, last crawl, referring sitemaps, and mobile/rich-result checks. THE tool for \"is this landing page even indexed, and if not why?\". The URL must belong to the siteUrl property. For several URLs, call this tool once per URL in parallel — there is no batch variant and the per-site quota is roomy (600 QPM).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"siteUrl",
"inspectionUrl"
],
"properties": {
"siteUrl": {
"type": "string",
"minLength": 1,
"description": "The Search Console property EXACTLY as search_console_list_sites returned it: 'sc-domain:example.com' or a URL-prefix like 'https://example.com/'. Never rewrite one form into the other."
},
"languageCode": {
"type": "string",
"minLength": 1,
"description": "BCP-47 language for result messages, e.g. en-US."
},
"inspectionUrl": {
"type": "string",
"minLength": 1,
"description": "The fully-qualified URL to inspect. Must belong to the siteUrl property."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"guidance": {
"type": "string",
"description": "What the user should do to connect Search Console."
},
"connected": {
"type": "boolean",
"const": false,
"description": "false when no Google Search Console connection exists — follow `guidance`; the data fields are absent."
},
"inspectionResult": {
"type": "object",
"properties": {
"ampResult": {
"type": "object",
"properties": {
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
}
},
"description": "AMP status, present for AMP pages only.",
"additionalProperties": {}
},
"indexStatusResult": {
"type": "object",
"properties": {
"sitemap": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sitemaps that list this URL."
},
"verdict": {
"type": "string",
"description": "PASS when indexed, NEUTRAL when excluded, FAIL or PARTIAL on errors."
},
"crawledAs": {
"type": "string",
"description": "The crawler used: DESKTOP or MOBILE."
},
"coverageState": {
"type": "string",
"description": "Google's reason, e.g. 'Submitted and indexed' or 'Crawled - currently not indexed'."
},
"indexingState": {
"type": "string",
"description": "Whether a noindex blocks indexing, e.g. INDEXING_ALLOWED or BLOCKED_BY_META_TAG."
},
"lastCrawlTime": {
"type": "string",
"description": "When Google last crawled the URL (ISO 8601)."
},
"referringUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Pages Google found linking to this URL."
},
"userCanonical": {
"type": "string",
"description": "The canonical URL the page declares."
},
"pageFetchState": {
"type": "string",
"description": "Outcome of the last fetch, e.g. SUCCESSFUL, NOT_FOUND or SERVER_ERROR."
},
"robotsTxtState": {
"type": "string",
"description": "Whether robots.txt allows the crawl: ALLOWED or DISALLOWED."
},
"googleCanonical": {
"type": "string",
"description": "The canonical URL Google chose."
}
},
"description": "Whether the URL is indexed, and why or why not.",
"additionalProperties": {}
},
"richResultsResult": {
"type": "object",
"properties": {
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
},
"detectedItems": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"description": "Rich result types found on the page, with their issues."
}
},
"description": "Structured data Google detected for rich results.",
"additionalProperties": {}
},
"inspectionResultLink": {
"type": "string",
"description": "This inspection in the Search Console UI."
},
"mobileUsabilityResult": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"verdict": {
"type": "string",
"description": "PASS, PARTIAL, FAIL, NEUTRAL or VERDICT_UNSPECIFIED."
}
},
"description": "Mobile usability. Google retired the report, so VERDICT_UNSPECIFIED is common.",
"additionalProperties": {}
}
},
"description": "Google's URL Inspection result for the URL.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Inspect a URL's index status",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Describe the Google Search Console connection — the data source, the granted scope (read-only), how sites are addressed (pass a siteUrl per call; discover them with search_console_list_sites), and the data caveats: 16-month retention, the 2-3 day finalized-data lag, and anonymised rare queries. Use when the user asks what you're connected to or what you can access. Takes no arguments.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"source",
"scope",
"siteModel",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "Retention, the finalized-data lag with today's default window, and query anonymisation."
},
"scope": {
"type": "string",
"description": "The OAuth scope, read-only."
},
"source": {
"type": "string",
"description": "Where the data comes from."
},
"siteModel": {
"type": "string",
"description": "How to pass a property as siteUrl."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_console_describe_server",
"title": "Describe Search Console data access",
"description": "Describe the Google Search Console connection — the data source, the granted scope (read-only), how sites are addressed (pass a siteUrl per call; discover them with search_console_list_sites), and the data caveats: 16-month retention, the 2-3 day finalized-data lag, and anonymised rare queries. Use when the user asks what you're connected to or what you can access. Takes no arguments.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"source",
"scope",
"siteModel",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "Retention, the finalized-data lag with today's default window, and query anonymisation."
},
"scope": {
"type": "string",
"description": "The OAuth scope, read-only."
},
"source": {
"type": "string",
"description": "Where the data comes from."
},
"siteModel": {
"type": "string",
"description": "How to pass a property as siteUrl."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Describe Search Console data access",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the Google Tag Manager accounts and containers this connection can access. Use this FIRST for any Tag Manager task: every other tag_manager_ tool takes the NUMERIC account_id and container_id from these rows — never the GTM-XXXXXXX public id, which is display-only. Rows are as HYPD last synced them: a container added in Google since then appears after the user refreshes Google Tag Manager on the Ad Platforms page. If nothing is returned, no Google Tag Manager Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms). IMPORTANT: the Tag Manager API allows only 25 requests per 100 seconds for ALL users combined — run tag_manager_ calls strictly sequentially, never in parallel.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"containers",
"truncated"
],
"properties": {
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"containers": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"planNotice": {
"type": "string"
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "tag_manager_list_containers",
"title": "List Tag Manager containers",
"description": "List the Google Tag Manager accounts and containers this connection can access. Use this FIRST for any Tag Manager task: every other tag_manager_ tool takes the NUMERIC account_id and container_id from these rows — never the GTM-XXXXXXX public id, which is display-only. Rows are as HYPD last synced them: a container added in Google since then appears after the user refreshes Google Tag Manager on the Ad Platforms page. If nothing is returned, no Google Tag Manager Connection exists yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms). IMPORTANT: the Tag Manager API allows only 25 requests per 100 seconds for ALL users combined — run tag_manager_ calls strictly sequentially, never in parallel.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"containers",
"truncated"
],
"properties": {
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"containers": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"planNotice": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Tag Manager containers",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
List a container's workspaces with their ids and descriptions. Workspaces are where edits live before they become a version — before ANY write, show the user this list and let THEM pick the workspace the change lands in (the Default Workspace is usually right, but an agency may keep staged work in others). Takes the numeric account_id and container_id from tag_manager_list_containers.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric GTM account id from tag_manager_list_containers.
Clear enough to supply this argument.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"workspaces",
"truncated"
],
"properties": {
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "tag_manager_list_workspaces",
"title": "List Tag Manager workspaces",
"description": "List a container's workspaces with their ids and descriptions. Workspaces are where edits live before they become a version — before ANY write, show the user this list and let THEM pick the workspace the change lands in (the Default Workspace is usually right, but an agency may keep staged work in others). Takes the numeric account_id and container_id from tag_manager_list_containers.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"containerId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric GTM account id from tag_manager_list_containers."
},
"containerId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"workspaces",
"truncated"
],
"properties": {
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Tag Manager workspaces",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
All tags, triggers, and variables of one workspace in a single call, plus clients and transformations on a server container — the orientation read for container health checks, conversion reconciliation against Google Ads conversion actions and GA4 key events, and "why isn't my conversion firing" questions (tag → trigger → variable), and for server-side tagging audits (which client claims a request, which transformation edits its event data before a tag sees it). Responses are cached for ~5 minutes (fromCache: true marks a cached read). Use this ONE call instead of fetching entities separately — the shared 25-per-100s API quota is the scarcest resource in this connector.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
accountId
The numeric GTM account id from tag_manager_list_containers.
Clear enough to supply this argument.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
Clear enough to supply this argument.
workspaceId
The workspace id from tag_manager_list_workspaces — the user picks where writes land.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"fromCache",
"tags",
"triggers",
"truncated",
"variables"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"clients": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Server containers only: the clients that claim requests."
},
"triggers": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"fromCache": {
"type": "boolean"
},
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"variables": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Server containers only: the transformations that edit event data before tags see it."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "tag_manager_get_container_snapshot",
"title": "Get container snapshot",
"description": "All tags, triggers, and variables of one workspace in a single call, plus clients and transformations on a server container — the orientation read for container health checks, conversion reconciliation against Google Ads conversion actions and GA4 key events, and \"why isn't my conversion firing\" questions (tag → trigger → variable), and for server-side tagging audits (which client claims a request, which transformation edits its event data before a tag sees it). Responses are cached for ~5 minutes (fromCache: true marks a cached read). Use this ONE call instead of fetching entities separately — the shared 25-per-100s API quota is the scarcest resource in this connector.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"containerId",
"workspaceId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric GTM account id from tag_manager_list_containers."
},
"containerId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id."
},
"workspaceId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The workspace id from tag_manager_list_workspaces — the user picks where writes land."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"fromCache",
"tags",
"triggers",
"truncated",
"variables"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"clients": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Server containers only: the clients that claim requests."
},
"triggers": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"fromCache": {
"type": "boolean"
},
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
},
"variables": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"transformations": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Server containers only: the transformations that edit event data before tags see it."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get container snapshot",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
The container version that is actually PUBLISHED right now (live: false means nothing was ever published). Compare against tag_manager_get_container_snapshot to catch live-vs-workspace drift — a fix that sits in a workspace but was never published is the most common "but I already fixed that". Cached ~5 minutes.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric GTM account id from tag_manager_list_containers.
Clear enough to supply this argument.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
{
"name": "tag_manager_get_live_version",
"title": "Get live container version",
"description": "The container version that is actually PUBLISHED right now (live: false means nothing was ever published). Compare against tag_manager_get_container_snapshot to catch live-vs-workspace drift — a fix that sits in a workspace but was never published is the most common \"but I already fixed that\". Cached ~5 minutes.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"containerId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric GTM account id from tag_manager_list_containers."
},
"containerId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"live",
"version"
],
"properties": {
"live": {
"type": "boolean"
},
"version": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get live container version",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description86/100
The container's version history (headers: version id, name, created time). Use it to find the two version ids for tag_manager_compare_versions when the user asks what changed, or the version to republish when a change must be rolled back.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
accountId
The numeric GTM account id from tag_manager_list_containers.
Clear enough to supply this argument.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
Describe the returned fields so an agent can interpret the result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"versions",
"truncated"
],
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "tag_manager_list_versions",
"title": "List container versions",
"description": "The container's version history (headers: version id, name, created time). Use it to find the two version ids for tag_manager_compare_versions when the user asks what changed, or the version to republish when a change must be rolled back.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"containerId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric GTM account id from tag_manager_list_containers."
},
"containerId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"versions",
"truncated"
],
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"truncated": {
"type": "boolean",
"description": "true when the list was cut short at the pagination bound — treat the data as INCOMPLETE and say so; never present a truncated list as the full container."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List container versions",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Semantic diff between two container versions: tags, triggers, and variables added, removed, and changed (field-level, both sides verbatim), plus clients and transformations on a server container. The tool for "tracking broke Tuesday — what changed?": list versions, pick the ones straddling the breakage, and read the delta instead of eyeballing two full containers.
The description explains the capability, when to use it, and what to expect.
Inputs70/100
3 of 4 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
accountId
Not provided
Missing description. Explain what this value means and how to supply it.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
Clear enough to supply this argument.
baseVersionId
The older version id (from tag_manager_list_versions).
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
One tag, trigger, or variable, or a server container's client or transformation, in full detail, including its typed parameters and fingerprint. Clients and transformations are read-only. Read the entity BEFORE proposing an edit: tag_manager_draft_entity_change updates send the full resource, so build the proposed entity from this read. The draft captures the current fingerprint itself, making the apply conditional — a change made elsewhere in between is rejected instead of overwritten.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
accountId
The numeric GTM account id from tag_manager_list_containers.
Clear enough to supply this argument.
containerId
The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id.
Clear enough to supply this argument.
workspaceId
The workspace id from tag_manager_list_workspaces — the user picks where writes land.
Clear enough to supply this argument.
entityType
Which entity kind this call addresses. client and transformation exist only in server containers.
Clear enough to supply this argument.
entityId
The entity's numeric id (tagId/triggerId/variableId, or clientId/transformationId, from the snapshot).
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get a Tag Manager entity",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema34/100
Describe the returned fields so an agent can interpret the result.
{
"name": "tag_manager_get_entity",
"title": "Get a Tag Manager entity",
"description": "One tag, trigger, or variable, or a server container's client or transformation, in full detail, including its typed parameters and fingerprint. Clients and transformations are read-only. Read the entity BEFORE proposing an edit: tag_manager_draft_entity_change updates send the full resource, so build the proposed entity from this read. The draft captures the current fingerprint itself, making the apply conditional — a change made elsewhere in between is rejected instead of overwritten.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"containerId",
"workspaceId",
"entityType",
"entityId"
],
"properties": {
"entityId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The entity's numeric id (tagId/triggerId/variableId, or clientId/transformationId, from the snapshot)."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric GTM account id from tag_manager_list_containers."
},
"entityType": {
"enum": [
"tag",
"trigger",
"variable",
"client",
"transformation"
],
"type": "string",
"description": "Which entity kind this call addresses. client and transformation exist only in server containers."
},
"containerId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The NUMERIC container id from tag_manager_list_containers — never the GTM-XXXXXXX public id."
},
"workspaceId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The workspace id from tag_manager_list_workspaces — the user picks where writes land."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"entity"
],
"properties": {
"entity": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a Tag Manager entity",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the user's connected Microsoft Advertising (Bing Ads) accounts. Use this first to discover the accountId every other microsoft_ads tool requires. Returns each account's id, display name, account number, and account status. If no accounts are returned, the user needs to connect Microsoft Advertising on the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the campaigns in a Microsoft Advertising (Bing Ads) account. Use when the user asks what Bing/Microsoft campaigns exist, their status, budget, or type, or before drilling into ad groups. Pass accountId from microsoft_ads_list_accounts. Rows are raw Microsoft campaign objects (Id, Name, Status, CampaignType, DailyBudget, ...). PerformanceMax campaigns have asset groups instead of ad groups — drill into them with microsoft_ads_list_asset_groups. Structural data only — for spend and performance use microsoft_ads_get_campaign_performance.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
{
"name": "microsoft_ads_list_campaigns",
"title": "List Microsoft Ads campaigns",
"description": "List the campaigns in a Microsoft Advertising (Bing Ads) account. Use when the user asks what Bing/Microsoft campaigns exist, their status, budget, or type, or before drilling into ad groups. Pass accountId from microsoft_ads_list_accounts. Rows are raw Microsoft campaign objects (Id, Name, Status, CampaignType, DailyBudget, ...). PerformanceMax campaigns have asset groups instead of ad groups — drill into them with microsoft_ads_list_asset_groups. Structural data only — for spend and performance use microsoft_ads_get_campaign_performance.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Microsoft Ads campaigns",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the ad groups in a Microsoft Advertising (Bing Ads) campaign. Pass accountId and campaignId (from microsoft_ads_list_campaigns). Rows are raw Microsoft ad group objects (Id, Name, Status, StartDate, EndDate, CpcBid, ...). Use before listing ads or keywords, which are scoped to an ad group. PerformanceMax campaigns have NO ad groups (an empty result there is correct) — use microsoft_ads_list_asset_groups for those.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
campaignId
The campaign id, from microsoft_ads_list_campaigns.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "List Microsoft Ads ad groups",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema49/100
Describe the returned fields so an agent can interpret the result.
{
"name": "microsoft_ads_list_ad_groups",
"title": "List Microsoft Ads ad groups",
"description": "List the ad groups in a Microsoft Advertising (Bing Ads) campaign. Pass accountId and campaignId (from microsoft_ads_list_campaigns). Rows are raw Microsoft ad group objects (Id, Name, Status, StartDate, EndDate, CpcBid, ...). Use before listing ads or keywords, which are scoped to an ad group. PerformanceMax campaigns have NO ad groups (an empty result there is correct) — use microsoft_ads_list_asset_groups for those.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"campaignId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts."
},
"campaignId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The campaign id, from microsoft_ads_list_campaigns."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Microsoft Ads ad groups",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the asset groups in a Microsoft Advertising (Bing Ads) PerformanceMax campaign. PMax campaigns have NO ad groups, ads, or keywords — asset groups are their only drill-down level. Pass accountId and campaignId (from microsoft_ads_list_campaigns, CampaignType PerformanceMax). Rows are slimmed for readability: name, asset group status, editorial status, business name, call to action, final URLs, headline/long-headline/description texts, image/video counts, and search themes. partialErrors carries any per-item failures Microsoft reported.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
campaignId
The PerformanceMax campaign id, from microsoft_ads_list_campaigns.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the ads in a Microsoft Advertising (Bing Ads) ad group, including responsive search ads with their headlines and descriptions. Pass accountId and adGroupId (from microsoft_ads_list_ad_groups). Rows are raw Microsoft ad objects covering all ad types (ResponsiveSearch, ExpandedText, Product, ...). Use for ad copy review and audits.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
adGroupId
The ad group id, from microsoft_ads_list_ad_groups.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List the keywords in a Microsoft Advertising (Bing Ads) ad group with match types, bids, and status. Pass accountId and adGroupId (from microsoft_ads_list_ad_groups). Rows are raw Microsoft keyword objects (Id, Text, MatchType, Bid, Status, ...). For keyword metrics and Quality Score use microsoft_ads_get_keyword_performance.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
adGroupId
The ad group id, from microsoft_ads_list_ad_groups.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
List the shared negative keyword lists in a Microsoft Advertising (Bing Ads) account library. Pass accountId. Rows are raw shared entity objects (Id, Name, ItemCount, ...). Use when auditing negative keyword coverage or investigating why queries are being blocked; a list's negative keywords and campaigns are on microsoft_ads_get_negative_keyword_lists.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List the negative keywords set on Microsoft Advertising (Bing Ads) ad groups or campaigns themselves, with their ids, text and match type. Pass accountId, entityType (ad_group or campaign) and entityIds (up to 50); for ad groups also campaignId, the campaign they are all in (from microsoft_ads_list_campaigns and microsoft_ads_list_ad_groups). Shared negative keyword lists are not included: see microsoft_ads_list_negative_keyword_lists. An entity Microsoft could not read is in partialErrors, named by EntityId.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
entityType
Whose own negative keywords to read.
Clear enough to supply this argument.
entityIds
The ad group or campaign ids; ad groups must all be in campaignId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
campaignId
Required for ad groups: the campaign they are in.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List the portfolio bid strategies in a Microsoft Advertising (Bing Ads) account: each one's id, name, scheme (e.g. MaxConversions), target CPA, target ROAS (a ratio, 4 is 400%) or max CPC, and the campaigns on it (campaignIds). Pass accountId, and optionally bidStrategyIds (up to 100) for just those. A campaign's own strategy is on microsoft_ads_list_campaigns rows (BiddingScheme, BidStrategyId).
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
bidStrategyIds
Only these portfolio strategies; omit for every one.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
List the sitelinks, callouts and structured snippets in a Microsoft Advertising (Bing Ads) account's extension library: each one's id, type, text (sitelink displayText, descriptions and finalUrl; callout text; snippet header and values), whether it runs on its own schedule, and where it serves (servesFrom: account, campaign:<id>; servesFromAdGroups when it is also linked to ad groups, which are not listed one by one). Pass accountId, and optionally types or extensionIds. Draft changes to them with microsoft_ads_draft_extension_changes.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
types
Only these types; omit for all three.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
extensionIds
Only these extensions; omit for every one.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
List the images in a Microsoft Advertising (Bing Ads) account's media library: each one's id, width and height in pixels, and a URL to view it. Pass accountId, and optionally imageIds for just those. Performance Max asset groups link library images by id, by shape: landscape 1.91:1 (at least 703×368), square 1:1 (470×470), portrait 1:2 (470×940), wide 4:1 (608×152), logos 1:1 (128×128) and landscape logos 4:1 (512×128). A build never uploads an image; pick ids from here for microsoft_ads_draft_campaign_build.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Find the location ids a Microsoft Advertising (Bing Ads) campaign targets, from Microsoft's own locations file. Pass accountId and queries (names, each looked up on its own: "Germany", "Berlin", or with its broader places, "Paris, France"), or locationIds to read locations back by id. Each match has its id, its full name (most to least specific), its type (Country, State, MetroArea, City, County, PostalCode) and its status: target Active ones; PendingDeprecation ones stop within 30 days, and Microsoft refuses Deprecated ones. Optional types narrows the matches, limit caps them per query. Use the ids in microsoft_ads_draft_campaign_build.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
queries
Names, each looked up on its own: "Germany", "Berlin", or with its broader places, "Paris, France".
Clear enough to supply this argument.
locationIds
Location ids to read back by id.
Clear enough to supply this argument.
types
Only these location types: Country, State, MetroArea, City, County, PostalCode.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
Matches per query; default 10.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Read shared negative keyword lists in a Microsoft Advertising (Bing Ads) account: each list's negative keywords (itemId, text, matchType) and the campaigns it is attached to (campaignIds). Pass accountId and listIds (up to 20) from microsoft_ads_list_negative_keyword_lists. The item ids are what microsoft_ads_draft_negative_keyword_list_changes removes.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
listIds
List ids from microsoft_ads_list_negative_keyword_lists.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List the audiences available to a Microsoft Advertising (Bing Ads) account — remarketing lists, in-market audiences, customer lists, custom/combined lists, and impression-based remarketing lists (customer- and account-scoped; Microsoft excludes its system-generated All Visitors / All Converters / Smart lists). Pass accountId. Rows are slimmed: name, audience type, scope, description, membership duration, audience network / search sizes, and supported campaign types. Use when auditing targeting options or checking remarketing list health. partialErrors carries any per-item failures Microsoft reported.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List the conversion goals in a Microsoft Advertising (Bing Ads) account with their tracking health. Pass accountId. Rows include name, goal type, category, goal status, tracking status (e.g. RecordedConversions vs NoRecentConversions), scope, exclude-from-bidding, enhanced conversions, attribution model, count type, conversion window, the UET tag id, and revenue settings. Use when diagnosing conversion tracking issues or auditing what the account optimizes toward. partialErrors carries any per-item failures Microsoft reported.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the UET (Universal Event Tracking) tags with their tracking status for a Microsoft Advertising (Bing Ads) connection. UET tags are customer-scoped, so this returns every tag the account's parent customer owns, not just the ones used by this account. Pass accountId. Rows include tag id, name, description, and tracking status (the raw tracking script is deliberately omitted). Use together with microsoft_ads_list_conversion_goals when diagnosing conversion tracking.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
{
"name": "microsoft_ads_list_uet_tags",
"title": "List Microsoft UET tags",
"description": "List the UET (Universal Event Tracking) tags with their tracking status for a Microsoft Advertising (Bing Ads) connection. UET tags are customer-scoped, so this returns every tag the account's parent customer owns, not just the ones used by this account. Pass accountId. Rows include tag id, name, description, and tracking status (the raw tracking script is deliberately omitted). Use together with microsoft_ads_list_conversion_goals when diagnosing conversion tracking.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"partialErrors",
"uetTags"
],
"properties": {
"uetTags": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"partialErrors": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List Microsoft UET tags",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the shared budgets in a Microsoft Advertising (Bing Ads) account library. Pass accountId. Rows include budget id, name, amount, budget type, and how many campaigns share it (associationCount). Campaigns using an individual (non-shared) budget do not appear here — check the campaign's own budget fields from microsoft_ads_list_campaigns instead. partialErrors carries any per-item failures Microsoft reported.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Campaign performance report for a Microsoft Advertising (Bing Ads) account: spend, impressions, clicks, CTR, average CPC/CPM, conversions, conversion rate, cost per conversion, revenue, and ROAS. Pass accountId plus startDate/endDate (YYYY-MM-DD). Aggregation 'Summary' (default) returns one totals row per campaign; 'Daily' adds a TimePeriod column with per-day rows. Values arrive as strings exactly as Microsoft reports them (some include % signs). The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
startDate
Report start date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
Report end date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
aggregation
'Summary' (default) returns one totals row per entity; 'Daily' adds a TimePeriod column with per-day rows.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Asset group performance report for Microsoft Advertising (Bing Ads) PerformanceMax campaigns: spend, impressions, clicks, CTR, average CPC, conversions, cost per conversion, revenue, and ROAS per asset group. This is the performance view for PMax — the campaign/keyword reports cover other campaign types. Pass accountId plus startDate/endDate (YYYY-MM-DD). Aggregation 'Summary' (default) returns one totals row per asset group; 'Daily' adds a TimePeriod column. Values arrive as strings exactly as Microsoft reports them (some include % signs). The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
startDate
Report start date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
Report end date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
aggregation
'Summary' (default) returns one totals row per entity; 'Daily' adds a TimePeriod column with per-day rows.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get Microsoft asset group performance",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema41/100
Describe the returned fields so an agent can interpret the result.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Keyword performance report for a Microsoft Advertising (Bing Ads) account, including Quality Score and its components (Expected CTR, Ad Relevance, Landing Page Experience) plus spend, clicks, impressions, conversions, revenue, and ROAS per keyword. Pass accountId plus startDate/endDate (YYYY-MM-DD); aggregation 'Summary' (default) or 'Daily'. Values arrive as strings. The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
startDate
Report start date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
Report end date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
aggregation
'Summary' (default) returns one totals row per entity; 'Daily' adds a TimePeriod column with per-day rows.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Search term (query) report for a Microsoft Advertising (Bing Ads) account: the actual search queries that triggered ads, with the matched keyword, match type, and performance metrics. Pass accountId plus startDate/endDate (YYYY-MM-DD); aggregation 'Summary' (default) or 'Daily'. Use for finding wasted spend and negative keyword candidates. Values arrive as strings. The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric Microsoft Advertising account id, from microsoft_ads_list_accounts.
Clear enough to supply this argument.
startDate
Report start date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
Report end date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
aggregation
'Summary' (default) returns one totals row per entity; 'Daily' adds a TimePeriod column with per-day rows.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the user's connected LinkedIn Ads accounts. Use this first to discover the accountId every other linkedin tool requires. Returns each account's numeric id, display name, currency, account status, and whether it is a test account — test accounts return NO analytics data, so warn the user before analyzing one. If no accounts are returned, the user needs to connect LinkedIn Ads on the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the campaign groups in a LinkedIn Ads account. TERMINOLOGY: a LinkedIn campaign group is the top budget/schedule container — it corresponds to what Meta and Google call a "campaign", so when the user says "my LinkedIn campaigns" they often mean campaign groups. Pass accountId from linkedin_list_ad_accounts. Rows are raw LinkedIn campaignGroup objects (id, name, status, runSchedule, totalBudget, ...). Structural data only — for spend and performance use linkedin_analytics. Paginate with pageToken from nextPageToken. Issue LinkedIn reads sequentially, not in parallel.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
Opaque cursor from a previous response's nextPageToken. Omit for the first page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "linkedin_get_campaign_groups",
"title": "Get LinkedIn campaign groups",
"description": "List the campaign groups in a LinkedIn Ads account. TERMINOLOGY: a LinkedIn campaign group is the top budget/schedule container — it corresponds to what Meta and Google call a \"campaign\", so when the user says \"my LinkedIn campaigns\" they often mean campaign groups. Pass accountId from linkedin_list_ad_accounts. Rows are raw LinkedIn campaignGroup objects (id, name, status, runSchedule, totalBudget, ...). Structural data only — for spend and performance use linkedin_analytics. Paginate with pageToken from nextPageToken. Issue LinkedIn reads sequentially, not in parallel.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"pageSize": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Rows per page (default 100, max 1000)."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "Opaque cursor from a previous response's nextPageToken. Omit for the first page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get LinkedIn campaign groups",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the campaigns in a LinkedIn Ads account. TERMINOLOGY: a LinkedIn campaign holds targeting, bidding, and format — it corresponds to what Meta calls an "ad set", one level BELOW a campaign group. Pass accountId from linkedin_list_ad_accounts; optionally pass campaignGroupId to restrict to one group. Rows are raw LinkedIn campaign objects (id, name, status, type, targetingCriteria, dailyBudget, ...). Structural data only — for spend and performance use linkedin_analytics. Paginate with pageToken from nextPageToken. Issue LinkedIn reads sequentially, not in parallel.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
campaignGroupId
Restrict to one campaign group, from linkedin_get_campaign_groups. Omit for all campaigns in the account.
Clear enough to supply this argument.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
Opaque cursor from a previous response's nextPageToken. Omit for the first page.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List individual ads in a connected LinkedIn Ads account, their intended/review status and campaign/content references. Pass accountId from linkedin_list_ad_accounts; optionally restrict with campaignIds. Returns raw creative objects. Resolve campaign URNs with linkedin_get_object. Copy and images are behind content references that this Connection cannot read directly: use the numeric creative id with linkedin_get_ad_preview for a browser preview, including drafts, video and carousel. Served ads may be enriched via linkedin_ad_library_search; its adUrl detail id matches the sponsoredCreative id. For performance, use linkedin_analytics with pivot CREATIVE. Pass nextPageToken as pageToken for subsequent pages. Call LinkedIn tools sequentially.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
campaignIds
Restrict to these campaigns. Omit for all creatives in the account.
Clear enough to supply this argument.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageToken
Opaque cursor from a previous response's nextPageToken. Omit for the first page.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "linkedin_get_creatives",
"title": "Get LinkedIn creatives",
"description": "List individual ads in a connected LinkedIn Ads account, their intended/review status and campaign/content references. Pass accountId from linkedin_list_ad_accounts; optionally restrict with campaignIds. Returns raw creative objects. Resolve campaign URNs with linkedin_get_object. Copy and images are behind content references that this Connection cannot read directly: use the numeric creative id with linkedin_get_ad_preview for a browser preview, including drafts, video and carousel. Served ads may be enriched via linkedin_ad_library_search; its adUrl detail id matches the sponsoredCreative id. For performance, use linkedin_analytics with pivot CREATIVE. Pass nextPageToken as pageToken for subsequent pages. Call LinkedIn tools sequentially.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"pageSize": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Rows per page (default 100, max 1000)."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts."
},
"pageToken": {
"type": "string",
"minLength": 1,
"description": "Opaque cursor from a previous response's nextPageToken. Omit for the first page."
},
"campaignIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d+$",
"description": "A campaign id, from linkedin_get_campaigns."
},
"maxItems": 20,
"minItems": 1,
"description": "Restrict to these campaigns. Omit for all creatives in the account."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"nextPageToken"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"nextPageToken": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get LinkedIn creatives",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Fetch one LinkedIn Ads entity by its URN — e.g. urn:li:sponsoredCampaign:123456789, urn:li:sponsoredCreative:987654321, or urn:li:adCampaignGroup:555. Use to resolve a URN reference returned by a list tool or an analytics pivot value into the full object (names, status, settings). Pass accountId from linkedin_list_ad_accounts plus the urn; the entity must belong to that account. For lists of entities use the dedicated list tools instead.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
urn
The entity URN, e.g. urn:li:sponsoredCampaign:123456789 or urn:li:sponsoredCreative:987654321 — as returned by the list tools.
{
"name": "linkedin_get_object",
"title": "Get a LinkedIn object",
"description": "Fetch one LinkedIn Ads entity by its URN — e.g. urn:li:sponsoredCampaign:123456789, urn:li:sponsoredCreative:987654321, or urn:li:adCampaignGroup:555. Use to resolve a URN reference returned by a list tool or an analytics pivot value into the full object (names, status, settings). Pass accountId from linkedin_list_ad_accounts plus the urn; the entity must belong to that account. For lists of entities use the dedicated list tools instead.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"urn"
],
"properties": {
"urn": {
"type": "string",
"pattern": "^urn:li:[A-Za-z][A-Za-z0-9]*:\\d+$",
"description": "The entity URN, e.g. urn:li:sponsoredCampaign:123456789 or urn:li:sponsoredCreative:987654321 — as returned by the list tools."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object"
],
"properties": {
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a LinkedIn object",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
SEE an actual ad from a connected LinkedIn Ads Account — LinkedIn's Accurate Preview of one creative, rendered exactly as it serves. Pass accountId (from linkedin_list_ad_accounts) and the numeric creativeId (the digits of urn:li:sponsoredCreative:<id>, from linkedin_get_creatives). Returns one preview per placement (desktop and mobile feed): previewUrl is a linkedin.com/ads/ad-preview link — Share it so the user can open the rendered ad in their browser. Links expire after ~3 hours; re-call for a fresh one instead of storing it, and never embed previewUrl or previewHtml in an artifact (the artifact sandbox blocks linkedin.com, so it renders blank there — the link is for the user to click). Works for single image, carousel, video, single job and event ads, INCLUDING drafts and unserved creatives the public Ad Library never indexes. Requires the connected member to hold any role on the LinkedIn Ads Account (VIEWER is enough). Issue LinkedIn reads sequentially, not in parallel.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
creativeId
The numeric creative id (the digits of urn:li:sponsoredCreative:<id>), from linkedin_get_creatives.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "linkedin_get_ad_preview",
"title": "Get LinkedIn ad preview",
"description": "SEE an actual ad from a connected LinkedIn Ads Account — LinkedIn's Accurate Preview of one creative, rendered exactly as it serves. Pass accountId (from linkedin_list_ad_accounts) and the numeric creativeId (the digits of urn:li:sponsoredCreative:<id>, from linkedin_get_creatives). Returns one preview per placement (desktop and mobile feed): previewUrl is a linkedin.com/ads/ad-preview link — Share it so the user can open the rendered ad in their browser. Links expire after ~3 hours; re-call for a fresh one instead of storing it, and never embed previewUrl or previewHtml in an artifact (the artifact sandbox blocks linkedin.com, so it renders blank there — the link is for the user to click). Works for single image, carousel, video, single job and event ads, INCLUDING drafts and unserved creatives the public Ad Library never indexes. Requires the connected member to hold any role on the LinkedIn Ads Account (VIEWER is enough). Issue LinkedIn reads sequentially, not in parallel.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"creativeId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts."
},
"creativeId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric creative id (the digits of urn:li:sponsoredCreative:<id>), from linkedin_get_creatives."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"creativeUrn",
"previews"
],
"properties": {
"previews": {
"type": "array",
"items": {
"type": "object",
"required": [
"placement",
"previewHtml",
"previewUrl"
],
"properties": {
"placement": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"previewUrl": {
"type": [
"string",
"null"
]
},
"previewHtml": {
"type": "string"
}
},
"additionalProperties": false
}
},
"creativeUrn": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get LinkedIn ad preview",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
LinkedIn Ads metrics over a date range, grouped by 1-3 pivots: CAMPAIGN_GROUP, CAMPAIGN, CREATIVE or firmographics such as MEMBER_JOB_TITLE, MEMBER_SENIORITY, MEMBER_INDUSTRY, MEMBER_COMPANY_SIZE and MEMBER_COUNTRY_V2. A LinkedIn campaign group corresponds to a Meta campaign; a LinkedIn campaign to a Meta ad set. Pass accountId, pivots, up to 20 camelCase metric fields and startDate/endDate. Resolve pivot URNs with linkedin_get_object or list tools. costInLocalCurrency uses the LinkedIn ad account currency. Results are not paginated, with a provider cap around 15000 rows: narrow dates or add entity filters. Demographic rows lag 12-24h, suppress counts under 3 events and are approximate; prefer timeGranularity ALL because daily sums can undercount. Call sequentially and chunk long date ranges to manage account-wide throttling.
The description explains the capability, when to use it, and what to expect.
Inputs78/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
pivots
1-3 dimensions to slice by. One pivot uses LinkedIn's finder q=analytics, 2-3 use q=statistics. Firmographic pivots (MEMBER_*) are the differentiator: performance by job title, seniority, industry, company size, or country.
Clear enough to supply this argument.
fields
1-20 camelCase metric fields, e.g. impressions, clicks, costInLocalCurrency, externalWebsiteConversions, oneClickLeads, videoViews, likes, comments, shares, follows. LinkedIn caps one request at 20 fields.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
startDate
Report start date, YYYY-MM-DD (inclusive).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
endDate
Report end date, YYYY-MM-DD (inclusive). Omit for today.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
timeGranularity
'ALL' (default) returns one totals row per pivot combination; 'DAILY'/'MONTHLY'/'YEARLY' add a time dimension. Note: demographic pivots suppress rows under 3 events, so daily sums can undercount period totals.
Clear enough to supply this argument.
campaignGroupIds
Restrict to these campaign group ids.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
campaignIds
Restrict to these campaign ids.
Explain the meaning of this value, not just its name.
creativeIds
Restrict to these creative ids.
Explain the meaning of this value, not just its name.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Estimate how many LinkedIn members a targeting definition reaches — no campaign needed. Use for planning questions like "how many senior marketers in DACH could we reach?". Pass accountId plus include clauses (each clause = one facet URN with its value URNs; clauses are ANDed, values within a clause ORed) and optional exclude clauses. Common facets: urn:li:adTargetingFacet:locations (values urn:li:geo:...), seniorities (urn:li:seniority:...), industries (urn:li:industry:...), staffCountRanges (urn:li:staffCountRange:...), titles (urn:li:title:...). Returns total targetable members; `active` is null because LinkedIn no longer populates it — never report an active-member count. A total of 0 also means "under 300" — LinkedIn reports audiences below its 300-member privacy floor as zero, so say "under 300", not "nobody".
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts.
Clear enough to supply this argument.
include › items › facet
The targeting facet URN, e.g. urn:li:adTargetingFacet:locations, urn:li:adTargetingFacet:seniorities, urn:li:adTargetingFacet:industries, urn:li:adTargetingFacet:staffCountRanges, urn:li:adTargetingFacet:titles.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
include › items › values
Entity URNs for this facet (e.g. urn:li:geo:103644278, urn:li:seniority:7). Values within one clause are ORed.
Clear enough to supply this argument.
exclude › items › facet
The targeting facet URN, e.g. urn:li:adTargetingFacet:locations, urn:li:adTargetingFacet:seniorities, urn:li:adTargetingFacet:industries, urn:li:adTargetingFacet:staffCountRanges, urn:li:adTargetingFacet:titles.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
exclude › items › values
Entity URNs for this facet (e.g. urn:li:geo:103644278, urn:li:seniority:7). Values within one clause are ORed.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "linkedin_audience_count",
"title": "Get LinkedIn audience count",
"description": "Estimate how many LinkedIn members a targeting definition reaches — no campaign needed. Use for planning questions like \"how many senior marketers in DACH could we reach?\". Pass accountId plus include clauses (each clause = one facet URN with its value URNs; clauses are ANDed, values within a clause ORed) and optional exclude clauses. Common facets: urn:li:adTargetingFacet:locations (values urn:li:geo:...), seniorities (urn:li:seniority:...), industries (urn:li:industry:...), staffCountRanges (urn:li:staffCountRange:...), titles (urn:li:title:...). Returns total targetable members; `active` is null because LinkedIn no longer populates it — never report an active-member count. A total of 0 also means \"under 300\" — LinkedIn reports audiences below its 300-member privacy floor as zero, so say \"under 300\", not \"nobody\".",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"include"
],
"properties": {
"exclude": {
"type": "array",
"items": {
"type": "object",
"required": [
"facet",
"values"
],
"properties": {
"facet": {
"type": "string",
"pattern": "^urn:li:adTargetingFacet:[A-Za-z][A-Za-z0-9]*$",
"description": "The targeting facet URN, e.g. urn:li:adTargetingFacet:locations, urn:li:adTargetingFacet:seniorities, urn:li:adTargetingFacet:industries, urn:li:adTargetingFacet:staffCountRanges, urn:li:adTargetingFacet:titles."
},
"values": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Entity URNs for this facet (e.g. urn:li:geo:103644278, urn:li:seniority:7). Values within one clause are ORed."
}
}
},
"maxItems": 10,
"minItems": 1,
"description": "Targeting clauses that remove members matching ANY of them (ORed)."
},
"include": {
"type": "array",
"items": {
"type": "object",
"required": [
"facet",
"values"
],
"properties": {
"facet": {
"type": "string",
"pattern": "^urn:li:adTargetingFacet:[A-Za-z][A-Za-z0-9]*$",
"description": "The targeting facet URN, e.g. urn:li:adTargetingFacet:locations, urn:li:adTargetingFacet:seniorities, urn:li:adTargetingFacet:industries, urn:li:adTargetingFacet:staffCountRanges, urn:li:adTargetingFacet:titles."
},
"values": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 100,
"minItems": 1,
"description": "Entity URNs for this facet (e.g. urn:li:geo:103644278, urn:li:seniority:7). Values within one clause are ORed."
}
}
},
"maxItems": 10,
"minItems": 1,
"description": "Targeting clauses a member must ALL match (ANDed). Values within one clause are ORed. E.g. one clause for locations, one for seniorities."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric LinkedIn Ads account id (the digits of urn:li:sponsoredAccount:<id>), from linkedin_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"total",
"active"
],
"properties": {
"total": {
"type": "number",
"description": "Targetable members. 0 also means 'under 300' — LinkedIn's privacy floor reports audiences below 300 as zero."
},
"active": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get LinkedIn audience count",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Search LinkedIn's public Ad Library for live and past ads across ALL advertisers (the LinkedIn counterpart of meta_ad_library_search). Pass at least one of keyword (words are ANDed), advertiser, or payerName; optionally countries (ISO codes), a date range, and targeting-facet filters. accountId is optional (default: the user's first connected LinkedIn Ads account) and only authenticates; results are not limited to it. endDate is EXCLUSIVE, and omitting the range returns only YESTERDAY's ads, so pass startDate for anything broader; coverage starts 2023-06-01. Up to 12 ads per call render as inline thumbnails, or with includeThumbnailData as a data URI on the row instead; rows carry headline, body, CTA, advertiser, adUrl, targeting and per-country impression RANGES (LinkedIn never publishes exact spend or impressions). Restricted ads and ads without a preview carry no thumbnail; adUrl always has the full ad. Paginate with count (max 25) and start, passing nextStart back until it is null.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The numeric id of one of the user's LinkedIn ad accounts, from linkedin_list_ad_accounts. Optional: without it, the user's first connected LinkedIn ad account is used; any one works, it only signs the request in.
Clear enough to supply this argument.
keyword
Keywords to search ad content for. Space-separated words are ANDed by LinkedIn.
Clear enough to supply this argument.
advertiser
Advertiser (company/page) name to search for.
Clear enough to supply this argument.
payerName
Who PAID for the ad — can differ from the advertiser (DSA transparency).
Clear enough to supply this argument.
countries
Two-letter ISO country codes the ads were served in, e.g. ["DE","US"]. Omit for all countries.
Clear enough to supply this argument.
startDate
Earliest serving date (YYYY-MM-DD). The library covers ads created on/after 2023-06-01.
Clear enough to supply this argument.
endDate
EXCLUSIVE end of the serving-date range (YYYY-MM-DD) — for a single day pass the next day. Omitting the whole range defaults to yesterday's ads.
Clear enough to supply this argument.
includedTargetingFacetCategories
Only ads that used AT LEAST one of these targeting categories.
Clear enough to supply this argument.
excludedTargetingFacetCategories
Only ads that used NONE of these targeting categories.
Clear enough to supply this argument.
count
Rows per page — LinkedIn caps the library at 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
includeThumbnailData
Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad.
Clear enough to supply this argument.
start
Offset for paging. Pass the previous response's nextStart.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Search the LinkedIn Ad Library",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema49/100
Describe the returned fields so an agent can interpret the result.
{
"name": "linkedin_ad_library_search",
"title": "Search the LinkedIn Ad Library",
"description": "Search LinkedIn's public Ad Library for live and past ads across ALL advertisers (the LinkedIn counterpart of meta_ad_library_search). Pass at least one of keyword (words are ANDed), advertiser, or payerName; optionally countries (ISO codes), a date range, and targeting-facet filters. accountId is optional (default: the user's first connected LinkedIn Ads account) and only authenticates; results are not limited to it. endDate is EXCLUSIVE, and omitting the range returns only YESTERDAY's ads, so pass startDate for anything broader; coverage starts 2023-06-01. Up to 12 ads per call render as inline thumbnails, or with includeThumbnailData as a data URI on the row instead; rows carry headline, body, CTA, advertiser, adUrl, targeting and per-country impression RANGES (LinkedIn never publishes exact spend or impressions). Restricted ads and ads without a preview carry no thumbnail; adUrl always has the full ad. Paginate with count (max 25) and start, passing nextStart back until it is null.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"count": {
"type": "integer",
"maximum": 25,
"minimum": 1,
"description": "Rows per page — LinkedIn caps the library at 25."
},
"start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Offset for paging. Pass the previous response's nextStart."
},
"endDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "EXCLUSIVE end of the serving-date range (YYYY-MM-DD) — for a single day pass the next day. Omitting the whole range defaults to yesterday's ads."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Keywords to search ad content for. Space-separated words are ANDed by LinkedIn."
},
"accountId": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric id of one of the user's LinkedIn ad accounts, from linkedin_list_ad_accounts. Optional: without it, the user's first connected LinkedIn ad account is used; any one works, it only signs the request in."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"maxItems": 20,
"minItems": 1,
"description": "Two-letter ISO country codes the ads were served in, e.g. [\"DE\",\"US\"]. Omit for all countries."
},
"payerName": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Who PAID for the ad — can differ from the advertiser (DSA transparency)."
},
"startDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Earliest serving date (YYYY-MM-DD). The library covers ads created on/after 2023-06-01."
},
"advertiser": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Advertiser (company/page) name to search for."
},
"includeThumbnailData": {
"type": "boolean",
"description": "Set true to receive each thumbnail as a data: URI (thumbnailDataUri) instead of an inline preview. Adds roughly 10-20 KB per ad."
},
"excludedTargetingFacetCategories": {
"type": "array",
"items": {
"enum": [
"LANGUAGE",
"LOCATION",
"AUDIENCE",
"AGE",
"GENDER",
"COMPANY",
"EDUCATION",
"JOB",
"INTERESTS",
"TRAITS"
],
"type": "string"
},
"minItems": 1,
"description": "Only ads that used NONE of these targeting categories."
},
"includedTargetingFacetCategories": {
"type": "array",
"items": {
"enum": [
"LANGUAGE",
"LOCATION",
"AUDIENCE",
"AGE",
"GENDER",
"COMPANY",
"EDUCATION",
"JOB",
"INTERESTS",
"TRAITS"
],
"type": "string"
},
"minItems": 1,
"description": "Only ads that used AT LEAST one of these targeting categories."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"total",
"nextStart"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"total": {
"type": [
"number",
"null"
],
"description": "Total matching ads, when LinkedIn reports it."
},
"nextStart": {
"type": [
"number",
"null"
],
"description": "Pass as `start` to read the next page; null when done."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search the LinkedIn Ad Library",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
List the TikTok Ads accounts (TikTok calls them advertisers) connected in Hypd, with each account's id, name, currency, timezone, status, and owning Business Center. Call this FIRST when working with TikTok Ads — it is the entry point and the account context to reuse for the rest of the conversation: pass the returned accountId (a long digit string; keep it as a string) to every other tiktok_ads_* tool. CURRENCY: money in every TikTok tool is in the account's currency listed here. Always state the currency with an amount, and never add up amounts from accounts or platforms in different currencies. When the user asks for one currency (e.g. TikTok next to Google Ads or Meta), convert explicitly and say which exchange rate you used and its date. TIMEZONE: report days are cut in the account's timezone. If nothing is returned, no TikTok account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
{
"name": "tiktok_ads_list_ad_accounts",
"title": "List TikTok ad accounts",
"description": "List the TikTok Ads accounts (TikTok calls them advertisers) connected in Hypd, with each account's id, name, currency, timezone, status, and owning Business Center. Call this FIRST when working with TikTok Ads — it is the entry point and the account context to reuse for the rest of the conversation: pass the returned accountId (a long digit string; keep it as a string) to every other tiktok_ads_* tool. CURRENCY: money in every TikTok tool is in the account's currency listed here. Always state the currency with an amount, and never add up amounts from accounts or platforms in different currencies. When the user asks for one currency (e.g. TikTok next to Google Ads or Meta), convert explicitly and say which exchange rate you used and its date. TIMEZONE: report days are cut in the account's timezone. If nothing is returned, no TikTok account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accounts"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"displayName",
"currency",
"timezone",
"accountStatus",
"ownerBusinessCenter"
],
"properties": {
"currency": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
},
"accountId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"accountStatus": {
"type": [
"string",
"null"
]
},
"ownerBusinessCenter": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"planNotice": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"title": "List TikTok ad accounts",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
List the campaigns in a TikTok Ads account: name, objective, budget, and status. Use when the user asks what campaigns exist, their objective or budget, or before drilling into ad groups and ads. Pass accountId from tiktok_ads_list_ad_accounts. Optionally filter by campaignIds (up to 100), objectiveType, primaryStatus (e.g. STATUS_DELIVERY_OK; deleted campaigns are excluded unless you ask for STATUS_DELETE or STATUS_ALL), or campaignAutomationType — Smart+ campaigns (SMART_PLUS, UPGRADED_SMART_PLUS) come back in the same list as MANUAL ones. Rows are TikTok's raw campaign objects. Page with page and pageSize (max 1000); totalNumber and totalPage say how many exist. Structural data only — for spend and performance use tiktok_ads_insights.
The description explains the capability, when to use it, and what to expect.
Inputs84/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
campaignIds
Restrict to these campaign ids (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objectiveType
Restrict to one objective, e.g. TRAFFIC, WEB_CONVERSIONS.
Clear enough to supply this argument.
campaignAutomationType
Restrict to manual or Smart+ campaigns; omit for both (they share the list).
Clear enough to supply this argument.
primaryStatus
Primary status filter, e.g. STATUS_DELIVERY_OK, STATUS_DISABLE, STATUS_ALL; deleted objects need STATUS_DELETE or STATUS_ALL.
Clear enough to supply this argument.
secondaryStatus
Secondary status filter (TikTok's detailed delivery status).
Explain the meaning of this value, not just its name.
page
Page number, from 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List the ad groups in a TikTok Ads account, with targeting, placements, optimization goal, bidding, budget, schedule, pixel and attribution settings. TERMINOLOGY: a TikTok ad group is what Meta calls an ad set — the level between campaign and ad that holds targeting and budget. Use when the user asks about audiences, placements, optimization, bids, budgets, or tracking setup. Pass accountId from tiktok_ads_list_ad_accounts; optionally filter by campaignIds or adgroupIds (up to 100 each) and primaryStatus. CAVEATS: the attribution window (click and view days) is fixed when an ad group is published — read it here before comparing TikTok conversions or ROAS with another platform. For conversion objectives the pixel sits on the ad group (pixel_id); a conversion ad group without one is misconfigured, not underperforming. Page with page and pageSize (max 1000). Structural data only — for performance use tiktok_ads_insights.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
campaignIds
Restrict to ad groups in these campaigns (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adgroupIds
Restrict to these ad group ids (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
primaryStatus
Primary status filter, e.g. STATUS_DELIVERY_OK, STATUS_DISABLE, STATUS_ALL; deleted objects need STATUS_DELETE or STATUS_ALL.
Clear enough to supply this argument.
secondaryStatus
Secondary status filter (TikTok's detailed delivery status).
Explain the meaning of this value, not just its name.
page
Page number, from 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "tiktok_ads_get_adgroups",
"title": "Get TikTok ad groups",
"description": "List the ad groups in a TikTok Ads account, with targeting, placements, optimization goal, bidding, budget, schedule, pixel and attribution settings. TERMINOLOGY: a TikTok ad group is what Meta calls an ad set — the level between campaign and ad that holds targeting and budget. Use when the user asks about audiences, placements, optimization, bids, budgets, or tracking setup. Pass accountId from tiktok_ads_list_ad_accounts; optionally filter by campaignIds or adgroupIds (up to 100 each) and primaryStatus. CAVEATS: the attribution window (click and view days) is fixed when an ad group is published — read it here before comparing TikTok conversions or ROAS with another platform. For conversion objectives the pixel sits on the ad group (pixel_id); a conversion ad group without one is misconfigured, not underperforming. Page with page and pageSize (max 1000). Structural data only — for performance use tiktok_ads_insights.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number, from 1."
},
"pageSize": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Rows per page (default 100, max 1000)."
},
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
},
"adgroupIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{1,20}$"
},
"maxItems": 100,
"minItems": 1,
"description": "Restrict to these ad group ids (up to 100)."
},
"campaignIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{1,20}$"
},
"maxItems": 100,
"minItems": 1,
"description": "Restrict to ad groups in these campaigns (up to 100)."
},
"primaryStatus": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]*$",
"maxLength": 64,
"description": "Primary status filter, e.g. STATUS_DELIVERY_OK, STATUS_DISABLE, STATUS_ALL; deleted objects need STATUS_DELETE or STATUS_ALL."
},
"secondaryStatus": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]*$",
"maxLength": 64,
"description": "Secondary status filter (TikTok's detailed delivery status)."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"page",
"pageSize",
"totalNumber",
"totalPage"
],
"properties": {
"page": {
"type": "number"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"pageSize": {
"type": "number"
},
"totalPage": {
"type": [
"number",
"null"
]
},
"totalNumber": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get TikTok ad groups",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List the ads in a TikTok Ads account: name, status, ad text, call to action, landing page, identity (the TikTok account the ad posts as, or the creator post a Spark Ad boosts), and video or image ids. Use when the user asks what ads are running or before looking at creative performance. Pass accountId from tiktok_ads_list_ad_accounts; optionally filter by campaignIds, adgroupIds or adIds (up to 100 each) and primaryStatus. Page with page and pageSize (max 1000). Structural data only — for performance use tiktok_ads_insights at data level AUCTION_AD.
The description explains the capability, when to use it, and what to expect.
Inputs78/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
campaignIds
Restrict to ads in these campaigns (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adgroupIds
Restrict to ads in these ad groups (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
adIds
Restrict to these ad ids (up to 100).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
primaryStatus
Primary status filter, e.g. STATUS_DELIVERY_OK, STATUS_DISABLE, STATUS_ALL; deleted objects need STATUS_DELETE or STATUS_ALL.
Clear enough to supply this argument.
secondaryStatus
Secondary status filter (TikTok's detailed delivery status).
Explain the meaning of this value, not just its name.
page
Page number, from 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Fetch one TikTok campaign, ad group, or ad by id with its full field set. Use when you already have an id (from a report row or a list) and need its details rather than listing siblings. Pass accountId from tiktok_ads_list_ad_accounts and objectId; pass level ('campaign', 'adgroup' or 'ad') when you know it — without it each level is tried in turn, which costs up to three lookups. Deleted objects are not found. For performance use tiktok_ads_insights.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
objectId
The campaign, ad group or ad id to fetch.
Clear enough to supply this argument.
level
The object's level when known; omit to try campaign, then ad group, then ad.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "tiktok_ads_get_object",
"title": "Get a TikTok object",
"description": "Fetch one TikTok campaign, ad group, or ad by id with its full field set. Use when you already have an id (from a report row or a list) and need its details rather than listing siblings. Pass accountId from tiktok_ads_list_ad_accounts and objectId; pass level ('campaign', 'adgroup' or 'ad') when you know it — without it each level is tried in turn, which costs up to three lookups. Deleted objects are not found. For performance use tiktok_ads_insights.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"objectId"
],
"properties": {
"level": {
"enum": [
"campaign",
"adgroup",
"ad"
],
"type": "string",
"description": "The object's level when known; omit to try campaign, then ad group, then ad."
},
"objectId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The campaign, ad group or ad id to fetch."
},
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"level",
"object"
],
"properties": {
"level": {
"enum": [
"campaign",
"adgroup",
"ad"
],
"type": "string"
},
"object": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a TikTok object",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
The performance tool for TikTok Ads: spend, impressions, clicks, conversions, ROAS and the video funnel for any account, campaign, ad group or ad. Pass accountId from tiktok_ads_list_ad_accounts, dimensions, metrics, and startDate/endDate (YYYY-MM-DD, inclusive, account timezone) or lifetime: true; set dataLevel to match the ID dimension. Values come back as TikTok's strings: "-" means not applicable and "<5" is a privacy floor, not a number. Money is in the account currency: state it and never add up different currencies. stat_time_day covers at most 30 days per call, stat_time_hour 1 day, anything else 365, so split longer ranges. truncated means over 20,000 ads: filter by campaign or ad group ids and repeat. billed_cost lags ~11h and cash_spend 24-48h. Attribution windows are fixed per ad group (tiktok_ads_get_adgroups): state them before comparing ROAS with Google or Meta. Report skan_* metrics separately. Call TikTok tools one at a time.
The description explains the capability, when to use it, and what to expect.
Inputs72/100
14 of 16 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
reportType
BASIC (default) for performance by object, time, country or ad type; AUDIENCE for breakdowns by age, gender, language, placement, platform, network (ac) or interest.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
dataLevel
Which objects are counted (default AUCTION_CAMPAIGN). Match it to the ID dimension.
Clear enough to supply this argument.
dimensions
What to group by: at most one ID dimension (advertiser_id, campaign_id, adgroup_id, ad_id) and one time dimension (stat_time_day, stat_time_hour), plus breakdowns for the report type.
Clear enough to supply this argument.
metrics
1-50 metrics from TikTok's report vocabulary.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Get the creative for a single TikTok ad: ad text, call to action, landing page, identity and media. Use when the user wants to review ad copy and creative or check the landing URL, or before judging a creative — pair it with tiktok_ads_insights at data level AUCTION_AD for the numbers (hook = video_watched_2s/6s, hold = p25-p50, payoff = p75-p100). Pass accountId from tiktok_ads_list_ad_accounts and adId from tiktok_ads_get_ads or a report row. Media thumbnails are returned inline (up to 12 per call; a video shows its cover frame); each media entry also carries url (the playable video or full-resolution image, signed, expires — urlExpiresAt when TikTok says), posterUrl (a video's cover), dimensions and durationSeconds. A Spark Ad's media comes from the TikTok post it boosts, whose caption and status are in sparkPost. Parts TikTok refuses (a post no longer shared, no permission on a video) come back as warnings while the rest still answers. TikTok offers no rendered-ad preview link for an existing ad.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
adId
The ad id, from tiktok_ads_get_ads or an AUCTION_AD report row.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Get a TikTok ad creative",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema46/100
Describe the returned fields so an agent can interpret the result.
{
"name": "tiktok_ads_get_creative",
"title": "Get a TikTok ad creative",
"description": "Get the creative for a single TikTok ad: ad text, call to action, landing page, identity and media. Use when the user wants to review ad copy and creative or check the landing URL, or before judging a creative — pair it with tiktok_ads_insights at data level AUCTION_AD for the numbers (hook = video_watched_2s/6s, hold = p25-p50, payoff = p75-p100). Pass accountId from tiktok_ads_list_ad_accounts and adId from tiktok_ads_get_ads or a report row. Media thumbnails are returned inline (up to 12 per call; a video shows its cover frame); each media entry also carries url (the playable video or full-resolution image, signed, expires — urlExpiresAt when TikTok says), posterUrl (a video's cover), dimensions and durationSeconds. A Spark Ad's media comes from the TikTok post it boosts, whose caption and status are in sparkPost. Parts TikTok refuses (a post no longer shared, no permission on a video) come back as warnings while the rest still answers. TikTok offers no rendered-ad preview link for an existing ad.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"adId"
],
"properties": {
"adId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The ad id, from tiktok_ads_get_ads or an AUCTION_AD report row."
},
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ad",
"media",
"sparkPost",
"warnings"
],
"properties": {
"ad": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"media": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"kind"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"video",
"image"
],
"type": "string"
},
"label": {
"type": "string"
},
"width": {
"type": [
"number",
"null"
]
},
"format": {
"type": [
"string",
"null"
]
},
"height": {
"type": [
"number",
"null"
]
},
"assetId": {
"type": [
"string",
"null"
]
},
"posterUrl": {
"type": [
"string",
"null"
]
},
"urlExpiresAt": {
"type": [
"string",
"null"
]
},
"durationSeconds": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"sparkPost": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get a TikTok ad creative",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Estimate reach for TikTok targeting without creating a campaign or spending ad budget. Use to size a proposed audience. Requires accountId, objectiveType, optimizationGoal and locationIds (TikTok ids, e.g. Germany 2921044). Optional ageGroups, gender, languages, interests, behaviors, audienceIds/excludedAudienceIds, placements and operatingSystem. Get interest ids from tiktok_ads_search_targeting; do not combine interestKeywordIds with purchaseIntentionKeywordIds. Get audience ids from tiktok_ads_audience_insights. Returns lowerEnd/upperEnd and userCountStage: 1 too narrow, 2 narrow, 3 balanced, 4 fairly broad. Relay this disclaimer verbatim when presenting estimates: "estimated audience size does not include audiences under 18 years of age; ad delivery as permitted by applicable laws is not affected".
The description explains the capability, when to use it, and what to expect.
Inputs52/100
16 of 22 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
objectiveType
Campaign objective, e.g. TRAFFIC, REACH, VIDEO_VIEWS, WEB_CONVERSIONS, APP_PROMOTION, LEAD_GENERATION.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
optimizationGoal
Ad group optimization goal, e.g. CLICK, REACH, CONVERT, VIDEO_VIEW, INSTALL.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
promotionType
Promotion type, when the objective needs one.
Explain the meaning of this value, not just its name.
locationIds
TikTok location ids to target (GeoNames ids, e.g. 2921044 Germany, 6252001 United States).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
placements
Selected placements; omit for automatic placement.
Clear enough to supply this argument.
ageGroups
Not provided
Missing description. Explain what this value means and how to supply it.
gender
Not provided
Missing description. Explain what this value means and how to supply it.
languages
Not provided
Missing description. Explain what this value means and how to supply it.
interestCategoryIds
General interest ids from tiktok_ads_search_targeting.
Explain the meaning of this value, not just its name.
interestKeywordIds
Additional interest ids from tiktok_ads_search_targeting. Not with purchaseIntentionKeywordIds.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
purchaseIntentionKeywordIds
Purchase intention ids from tiktok_ads_search_targeting.
Explain the meaning of this value, not just its name.
actions › items › actionScene
Not provided
Missing description. Explain what this value means and how to supply it.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
TikTok audience reads selected by inputs. accountId alone lists custom/lookalike audiences with paging. customAudienceId or countryCodes (max 5, optional targeting filters) returns audience profiles; choose up to 6 dimensions such as age, gender, country, top_regions, OS, device_price, interests or hashtags. Defaults: age, gender, top_interests. Each dimension makes a TikTok call. With countryCodes, top_regions describes only the first country; request countries separately for regional comparisons. customAudienceId + compareWithCustomAudienceIds (max 4) returns overlap. Profile rates are fractions (0-1). all represents the whole chosen market and is empty for custom audiences or audiences below 1000 people. Use returned audience ids with tiktok_ads_estimate_audience_size.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
customAudienceId
Profile this custom audience, or with compareWithCustomAudienceIds use it as the overlap benchmark.
Clear enough to supply this argument.
compareWithCustomAudienceIds
Up to 4 audiences to measure overlap against customAudienceId.
Clear enough to supply this argument.
countryCodes
Profile the potential audience in these countries (instead of a custom audience).
Clear enough to supply this argument.
dimensions
Profile dimensions (default age, gender, top_interests). Each is one TikTok call.
Clear enough to supply this argument.
ageGroups
Narrow a countryCodes profile to these ages.
Clear enough to supply this argument.
gender
Narrow a countryCodes profile to these genders.
Clear enough to supply this argument.
languages
Narrow a countryCodes profile to these languages.
Clear enough to supply this argument.
interestCategoryIds
Narrow a countryCodes profile to these interests.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
page
Page number, from 1.
Clarify units, where to obtain this value, or conventions not already expressed in the schema.
pageSize
Rows per page (default 100, max 1000).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Find TikTok interest, behavior and hashtag targeting by keyword — the ids a targeting recommendation or tiktok_ads_estimate_audience_size needs. Pass accountId and keywords (1-10 words or short phrases, in the language given by language, default en). Optionally restrict types: GENERAL_INTEREST, ADDITIONAL_INTEREST, PURCHASE_INTENTION, VIDEO_INTERACTION, CREATOR_INTERACTION, HASHTAG_INTERACTION; with more than one keyword TikTok only supports ADDITIONAL_INTEREST and HASHTAG_INTERACTION, so search one keyword at a time for the others. Results are grouped by type, then by keyword, each with an id and name. General interest ids go to interestCategoryIds, additional interests to interestKeywordIds, purchase intentions to purchaseIntentionKeywordIds, and video/creator/hashtag ids to behavior actions. This is not a location search.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
keywords
1-10 seed keywords, e.g. ['yoga'].
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
types
Restrict to these targeting types; omit for all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
Language of the keywords (default en).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "tiktok_ads_search_targeting",
"title": "Search TikTok targeting",
"description": "Find TikTok interest, behavior and hashtag targeting by keyword — the ids a targeting recommendation or tiktok_ads_estimate_audience_size needs. Pass accountId and keywords (1-10 words or short phrases, in the language given by language, default en). Optionally restrict types: GENERAL_INTEREST, ADDITIONAL_INTEREST, PURCHASE_INTENTION, VIDEO_INTERACTION, CREATOR_INTERACTION, HASHTAG_INTERACTION; with more than one keyword TikTok only supports ADDITIONAL_INTEREST and HASHTAG_INTERACTION, so search one keyword at a time for the others. Results are grouped by type, then by keyword, each with an id and name. General interest ids go to interestCategoryIds, additional interests to interestKeywordIds, purchase intentions to purchaseIntentionKeywordIds, and video/creator/hashtag ids to behavior actions. This is not a location search.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId",
"keywords"
],
"properties": {
"types": {
"type": "array",
"items": {
"enum": [
"GENERAL_INTEREST",
"ADDITIONAL_INTEREST",
"PURCHASE_INTENTION",
"VIDEO_INTERACTION",
"CREATOR_INTERACTION",
"HASHTAG_INTERACTION"
],
"type": "string"
},
"maxItems": 6,
"minItems": 1,
"description": "Restrict to these targeting types; omit for all."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"maxItems": 10,
"minItems": 1,
"description": "1-10 seed keywords, e.g. ['yoga']."
},
"language": {
"enum": [
"ar",
"cs",
"de",
"en",
"es",
"fr",
"id",
"it",
"ja",
"ko",
"ms",
"pl",
"pt",
"ru",
"sv",
"th",
"tr",
"vi",
"zh"
],
"type": "string",
"description": "Language of the keywords (default en)."
},
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search TikTok targeting",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
List a TikTok advertiser's pixels and their events (the conversion events the pixel tracks). Use when checking tracking before judging conversion performance, or when the user asks what TikTok measures on their site. Pass accountId from tiktok_ads_list_ad_accounts; optionally pixelId for one pixel. Up to 20 per page. CAVEAT: for conversion objectives the pixel is set on the ad group (pixel_id in tiktok_ads_get_adgroups) — an ad group with a conversion objective and no pixel is misconfigured, not underperforming. For whether a pixel stopped firing, see tiktok_ads_get_diagnosis (EVENT_TRACK).
The description explains the capability, when to use it, and what to expect.
Inputs69/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pixelId
Fetch just this pixel.
Explain the meaning of this value, not just its name.
page
Page number, from 1.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pageSize
Pixels per page (max 20, TikTok's cap).
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "tiktok_ads_list_pixels",
"title": "List TikTok pixels",
"description": "List a TikTok advertiser's pixels and their events (the conversion events the pixel tracks). Use when checking tracking before judging conversion performance, or when the user asks what TikTok measures on their site. Pass accountId from tiktok_ads_list_ad_accounts; optionally pixelId for one pixel. Up to 20 per page. CAVEAT: for conversion objectives the pixel is set on the ad group (pixel_id in tiktok_ads_get_adgroups) — an ad group with a conversion objective and no pixel is misconfigured, not underperforming. For whether a pixel stopped firing, see tiktok_ads_get_diagnosis (EVENT_TRACK).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number, from 1."
},
"pixelId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "Fetch just this pixel."
},
"pageSize": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Pixels per page (max 20, TikTok's cap)."
},
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"pixels",
"page",
"pageSize",
"totalNumber"
],
"properties": {
"page": {
"type": "number"
},
"pixels": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"pageSize": {
"type": "number"
},
"totalNumber": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"annotations": {
"title": "List TikTok pixels",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
TikTok's own diagnoses and suggestions for active ad groups: creative issues (no background music, short or low-resolution video), bid and budget suggestions (a suggested bid or budget, estimated delivery at other levels), and event tracking problems (a pixel with no activity in 7 days). Pass accountId; optionally adgroupIds (up to 20) and issueCategories (CREATIVE, BID_AND_BUDGET, EVENT_TRACK). Only ad groups WITH suggestions are returned, so an empty list means TikTok found nothing to flag, not an error. These are TikTok's suggestions, returned verbatim — present them as TikTok's, weigh them against the account's goals, and do not restate them as your own findings.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
accountId
The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts.
Clear enough to supply this argument.
adgroupIds
Only these ad groups (up to 20); omit for all active ones.
Clear enough to supply this argument.
issueCategories
Only these issue categories; omit for all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Declare the result fields and their types in the output schema.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Ad groups with suggestions only: an empty list means TikTok flagged nothing."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "tiktok_ads_get_diagnosis",
"title": "Get TikTok ad diagnoses",
"description": "TikTok's own diagnoses and suggestions for active ad groups: creative issues (no background music, short or low-resolution video), bid and budget suggestions (a suggested bid or budget, estimated delivery at other levels), and event tracking problems (a pixel with no activity in 7 days). Pass accountId; optionally adgroupIds (up to 20) and issueCategories (CREATIVE, BID_AND_BUDGET, EVENT_TRACK). Only ad groups WITH suggestions are returned, so an empty list means TikTok found nothing to flag, not an error. These are TikTok's suggestions, returned verbatim — present them as TikTok's, weigh them against the account's goals, and do not restate them as your own findings.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "string",
"pattern": "^\\d{1,20}$",
"description": "The TikTok advertiser id (a long digit string — keep it as a string), from tiktok_ads_list_ad_accounts."
},
"adgroupIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{1,20}$"
},
"maxItems": 20,
"minItems": 1,
"description": "Only these ad groups (up to 20); omit for all active ones."
},
"issueCategories": {
"type": "array",
"items": {
"enum": [
"CREATIVE",
"BID_AND_BUDGET",
"EVENT_TRACK"
],
"type": "string"
},
"maxItems": 3,
"minItems": 1,
"description": "Only these issue categories; omit for all."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Ad groups with suggestions only: an empty list means TikTok flagged nothing."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Get TikTok ad diagnoses",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Step 2 of 3: record the User's approval. Call this ONLY after you showed the User every change (a short summary of the diff, current → proposed) and the reasoning, and they replied with an explicit yes to those exact changes. Pass their reply verbatim as userConfirmation; it is stored as the record of consent. Show every warning too and pass the rule ids they still said yes to as acknowledgedWarnings; approval is refused while one is left out. Never approve on the User's behalf or infer approval from the original request. One draft: draftId. Several drafts one request made, shown together and given one yes: draftIds, approved all or none (an enable is approved on its own). A multi-Account batch: its batchId. A draft that is invalid, expired, superseded or already applied cannot be approved. Then call apply_change_draft with the same draftId, draftIds or batchId.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
draftId
The draftId a draft tool returned. Pass exactly one of draftId, batchId or draftIds.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
batchId
In place of draftId, never with it: the batchId a multi-Account draft returned. Covers every Account's draft at once.
Clear enough to supply this argument.
draftIds
In place of draftId and batchId: the draftIds of several drafts the User saw together and said one yes to (2 to 20). All are approved or none; each still applies, is re-checked and undone on its own. An enable is approved on its own, never beside other changes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
userConfirmation
The User's reply, verbatim, after you showed them every operation and the reasoning. Must be an explicit yes to these exact changes; never paraphrase, never fill in on their behalf. Left out only when the draft's nextStep says HYPD asks the User in a form.
Clear enough to supply this argument.
summary
Only when the draft's next step says HYPD asks the User in a form: one line naming these changes, in the User's own language. The form shows it above the changes.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
acknowledgedWarnings
The rule id of every warning on the draft that you showed the User and they still said yes to. Approval is refused while any warning is left out.
{
"name": "approve_change_draft",
"title": "Approve a change draft",
"description": "Step 2 of 3: record the User's approval. Call this ONLY after you showed the User every change (a short summary of the diff, current → proposed) and the reasoning, and they replied with an explicit yes to those exact changes. Pass their reply verbatim as userConfirmation; it is stored as the record of consent. Show every warning too and pass the rule ids they still said yes to as acknowledgedWarnings; approval is refused while one is left out. Never approve on the User's behalf or infer approval from the original request. One draft: draftId. Several drafts one request made, shown together and given one yes: draftIds, approved all or none (an enable is approved on its own). A multi-Account batch: its batchId. A draft that is invalid, expired, superseded or already applied cannot be approved. Then call apply_change_draft with the same draftId, draftIds or batchId.",
"inputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"draftId"
]
},
{
"required": [
"batchId"
]
},
{
"required": [
"draftIds"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"batchId": {
"type": "string",
"minLength": 1,
"description": "In place of draftId, never with it: the batchId a multi-Account draft returned. Covers every Account's draft at once."
},
"draftId": {
"type": "string",
"minLength": 1,
"description": "The draftId a draft tool returned. Pass exactly one of draftId, batchId or draftIds."
},
"summary": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Only when the draft's next step says HYPD asks the User in a form: one line naming these changes, in the User's own language. The form shows it above the changes."
},
"draftIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 20,
"minItems": 2,
"description": "In place of draftId and batchId: the draftIds of several drafts the User saw together and said one yes to (2 to 20). All are approved or none; each still applies, is re-checked and undone on its own. An enable is approved on its own, never beside other changes."
},
"userConfirmation": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The User's reply, verbatim, after you showed them every operation and the reasoning. Must be an explicit yes to these exact changes; never paraphrase, never fill in on their behalf. Left out only when the draft's nextStep says HYPD asks the User in a form."
},
"acknowledgedWarnings": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 50,
"description": "The rule id of every warning on the draft that you showed the User and they still said yes to. Approval is refused while any warning is left out."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"draftStatus",
"nextStep",
"operationCount",
"writeAction"
],
"properties": {
"drafts": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"draftId"
],
"properties": {
"draftId": {
"type": "string"
},
"accountId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"batchId": {
"type": "string"
},
"draftId": {
"type": "string"
},
"nextStep": {
"type": "string",
"description": "What to do now. Follow it."
},
"accountId": {
"type": "string"
},
"draftStatus": {
"type": "string",
"const": "approved"
},
"writeAction": {
"type": "string"
},
"operationCount": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Approve a change draft",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
List the Change Drafts made through HYPD on the User's Google Ads Accounts, newest first: what was proposed (diff, current → proposed), the reasoning, the User's approval in their own words, and what landed after the apply. Use it before proposing a change, to build on what was already tried and why, to answer what HYPD changed in an Account, and to learn how a draft ended: applied, or stopped, with recheck naming what changed in the Account since the approval. Filter by googleAdsId and draftStatus; limit defaults to 10, max 50. Reads HYPD's Change History only, never Google, so changes made outside HYPD are not listed. changeHistoryUrl is the same history in the HYPD app.
The description explains the capability, when to use it, and what to expect.
Inputs83/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
googleAdsId
The Google Ads Account whose changes to list. Omit for every Account.
Clear enough to supply this argument.
draftStatus
Only drafts in this Draft Status.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
How many drafts, newest first. Default 10, max 50.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "List changes made through HYPD",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
Output schema88/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"changeHistoryUrl",
"changes",
"truncated"
],
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"draftId",
"accountId",
"createdAt",
"draftStatus",
"writeAction",
"operationCount",
"reasoning"
],
"properties": {
"diff": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"resourceName",
"label",
"fields"
],
"properties": {
"index": {
"type": "number",
"description": "Position in the operations array."
},
"label": {
"type": "string",
"description": "What the operation touches, for the User."
},
"before": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "The target's full state when drafted; null when Google did not return it. Absent for a create."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"current",
"proposed"
],
"properties": {
"name": {
"type": "string"
},
"current": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value now; null when unset or not created yet."
},
"proposed": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"description": "Every field this operation changes, current → proposed."
},
"resourceName": {
"type": [
"string",
"null"
],
"description": "The resource this operation changes; null for a create."
}
},
"additionalProperties": false
},
"description": "Current → proposed per operation, as read at draft time."
},
"error": {
"type": "string"
},
"landed": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"resourceName",
"fields"
],
"properties": {
"index": {
"type": "number",
"description": "Position in the operations array."
},
"fields": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "The resource as Google reports it now, by the diff's field names; null when it no longer exists."
},
"resourceName": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "What Google reported right after the apply."
},
"draftId": {
"type": "string"
},
"payload": {
"description": "Only on drafts older than diff: the operations as drafted."
},
"recheck": {
"type": "object",
"required": [
"drift",
"findings"
],
"properties": {
"drift": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"label",
"field",
"approved",
"now"
],
"properties": {
"now": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value just before the run."
},
"field": {
"type": "string"
},
"index": {
"type": "number",
"description": "Position in the operations array."
},
"label": {
"type": "string"
},
"approved": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value when the User approved."
}
},
"additionalProperties": false
},
"description": "Each value that changed since the User approved."
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"rule",
"tier",
"message"
],
"properties": {
"rule": {
"type": "string"
},
"tier": {
"type": "string"
},
"message": {
"type": "string"
},
"evidence": {
"description": "The numbers the guardrail fired on, as it recorded them."
}
},
"additionalProperties": false
},
"description": "Guardrails that now block, or warn without the User's yes."
}
},
"description": "Why a stopped draft was not sent: what the re-check before the run found. Draft again from the Account as it is now.",
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [
"rule",
"tier",
"message"
],
"properties": {
"rule": {
"type": "string"
},
"tier": {
"type": "string"
},
"message": {
"type": "string"
},
"evidence": {
"description": "The numbers the guardrail fired on, as it recorded them."
}
},
"additionalProperties": false
}
},
"accountId": {
"type": "string"
},
"appliedAt": {
"type": "string"
},
"createdAt": {
"type": "string",
"description": "ISO 8601."
},
"expiresAt": {
"type": "string",
"description": "Set while the draft still waits for approval or apply."
},
"reasoning": {
"type": "string",
"description": "Why the agent proposed it, as drafted."
},
"approvedAt": {
"type": "string"
},
"supersedes": {
"type": "string"
},
"cancelledAt": {
"type": "string"
},
"draftStatus": {
"enum": [
"validated",
"approved",
"applied",
"invalid",
"partially_applied",
"failed",
"expired",
"superseded",
"scheduled",
"cancelled",
"stopped",
"outcome_unknown"
],
"type": "string"
},
"writeAction": {
"type": "string"
},
"scheduledFor": {
"type": "string",
"description": "When a scheduled draft runs, or ran."
},
"supersededBy": {
"type": "string"
},
"operationCount": {
"type": "number"
},
"reconciliation": {
"type": "object",
"required": [
"operations"
],
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"label",
"verdict"
],
"properties": {
"index": {
"type": "number"
},
"label": {
"type": "string"
},
"verdict": {
"enum": [
"landed",
"not_landed",
"unknown"
],
"type": "string",
"description": "landed: the target holds the proposed value. not_landed: it still holds the old one. unknown: a create, or neither."
}
},
"additionalProperties": false
}
}
},
"description": "Set when the run lost the platform's answer: what re-reading each target found.",
"additionalProperties": false
},
"userConfirmation": {
"type": "string",
"description": "The User's reply at approval, verbatim."
},
"acknowledgedWarnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"description": "Newest first."
},
"truncated": {
"type": "boolean",
"description": "true when the draftStatus filter stopped before reading the oldest drafts: there may be more matching ones. Narrow with googleAdsId or drop draftStatus."
},
"changeHistoryUrl": {
"type": "string",
"description": "The Change History page in the HYPD app, for the User."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "google_ads_list_changes",
"title": "List changes made through HYPD",
"description": "List the Change Drafts made through HYPD on the User's Google Ads Accounts, newest first: what was proposed (diff, current → proposed), the reasoning, the User's approval in their own words, and what landed after the apply. Use it before proposing a change, to build on what was already tried and why, to answer what HYPD changed in an Account, and to learn how a draft ended: applied, or stopped, with recheck naming what changed in the Account since the approval. Filter by googleAdsId and draftStatus; limit defaults to 10, max 50. Reads HYPD's Change History only, never Google, so changes made outside HYPD are not listed. changeHistoryUrl is the same history in the HYPD app.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "How many drafts, newest first. Default 10, max 50."
},
"draftStatus": {
"enum": [
"validated",
"approved",
"applied",
"invalid",
"partially_applied",
"failed",
"expired",
"superseded",
"scheduled",
"cancelled",
"stopped",
"outcome_unknown"
],
"type": "string",
"description": "Only drafts in this Draft Status."
},
"googleAdsId": {
"type": "string",
"pattern": "^\\d(?:[ -]*\\d)*$",
"description": "The Google Ads Account whose changes to list. Omit for every Account."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"changeHistoryUrl",
"changes",
"truncated"
],
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"required": [
"draftId",
"accountId",
"createdAt",
"draftStatus",
"writeAction",
"operationCount",
"reasoning"
],
"properties": {
"diff": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"resourceName",
"label",
"fields"
],
"properties": {
"index": {
"type": "number",
"description": "Position in the operations array."
},
"label": {
"type": "string",
"description": "What the operation touches, for the User."
},
"before": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "The target's full state when drafted; null when Google did not return it. Absent for a create."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"current",
"proposed"
],
"properties": {
"name": {
"type": "string"
},
"current": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value now; null when unset or not created yet."
},
"proposed": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"description": "Every field this operation changes, current → proposed."
},
"resourceName": {
"type": [
"string",
"null"
],
"description": "The resource this operation changes; null for a create."
}
},
"additionalProperties": false
},
"description": "Current → proposed per operation, as read at draft time."
},
"error": {
"type": "string"
},
"landed": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"resourceName",
"fields"
],
"properties": {
"index": {
"type": "number",
"description": "Position in the operations array."
},
"fields": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
},
{
"type": "null"
}
],
"description": "The resource as Google reports it now, by the diff's field names; null when it no longer exists."
},
"resourceName": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "What Google reported right after the apply."
},
"draftId": {
"type": "string"
},
"payload": {
"description": "Only on drafts older than diff: the operations as drafted."
},
"recheck": {
"type": "object",
"required": [
"drift",
"findings"
],
"properties": {
"drift": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"label",
"field",
"approved",
"now"
],
"properties": {
"now": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value just before the run."
},
"field": {
"type": "string"
},
"index": {
"type": "number",
"description": "Position in the operations array."
},
"label": {
"type": "string"
},
"approved": {
"type": [
"string",
"number",
"boolean",
"null"
],
"description": "The value when the User approved."
}
},
"additionalProperties": false
},
"description": "Each value that changed since the User approved."
},
"findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"rule",
"tier",
"message"
],
"properties": {
"rule": {
"type": "string"
},
"tier": {
"type": "string"
},
"message": {
"type": "string"
},
"evidence": {
"description": "The numbers the guardrail fired on, as it recorded them."
}
},
"additionalProperties": false
},
"description": "Guardrails that now block, or warn without the User's yes."
}
},
"description": "Why a stopped draft was not sent: what the re-check before the run found. Draft again from the Account as it is now.",
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [
"rule",
"tier",
"message"
],
"properties": {
"rule": {
"type": "string"
},
"tier": {
"type": "string"
},
"message": {
"type": "string"
},
"evidence": {
"description": "The numbers the guardrail fired on, as it recorded them."
}
},
"additionalProperties": false
}
},
"accountId": {
"type": "string"
},
"appliedAt": {
"type": "string"
},
"createdAt": {
"type": "string",
"description": "ISO 8601."
},
"expiresAt": {
"type": "string",
"description": "Set while the draft still waits for approval or apply."
},
"reasoning": {
"type": "string",
"description": "Why the agent proposed it, as drafted."
},
"approvedAt": {
"type": "string"
},
"supersedes": {
"type": "string"
},
"cancelledAt": {
"type": "string"
},
"draftStatus": {
"enum": [
"validated",
"approved",
"applied",
"invalid",
"partially_applied",
"failed",
"expired",
"superseded",
"scheduled",
"cancelled",
"stopped",
"outcome_unknown"
],
"type": "string"
},
"writeAction": {
"type": "string"
},
"scheduledFor": {
"type": "string",
"description": "When a scheduled draft runs, or ran."
},
"supersededBy": {
"type": "string"
},
"operationCount": {
"type": "number"
},
"reconciliation": {
"type": "object",
"required": [
"operations"
],
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"label",
"verdict"
],
"properties": {
"index": {
"type": "number"
},
"label": {
"type": "string"
},
"verdict": {
"enum": [
"landed",
"not_landed",
"unknown"
],
"type": "string",
"description": "landed: the target holds the proposed value. not_landed: it still holds the old one. unknown: a create, or neither."
}
},
"additionalProperties": false
}
}
},
"description": "Set when the run lost the platform's answer: what re-reading each target found.",
"additionalProperties": false
},
"userConfirmation": {
"type": "string",
"description": "The User's reply at approval, verbatim."
},
"acknowledgedWarnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"description": "Newest first."
},
"truncated": {
"type": "boolean",
"description": "true when the draftStatus filter stopped before reading the oldest drafts: there may be more matching ones. Narrow with googleAdsId or drop draftStatus."
},
"changeHistoryUrl": {
"type": "string",
"description": "The Change History page in the HYPD app, for the User."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List changes made through HYPD",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Searches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privacy and data access, what HYPD can do, and setting HYPD up in Claude, ChatGPT or other AI clients. Returns the matching articles' text and links; answer from them and cite them. Not for advertising advice or the user's account data; use the platform tools for those.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
question
The user's question about HYPD, in their words, e.g. 'How do I connect my Google Ads account?'
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Search the HYPD help center",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema74/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"articles",
"help_center_url",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How these results relate to the question."
},
"status": {
"enum": [
"ok",
"no_results"
],
"type": "string",
"description": "no_results when no article matched."
},
"articles": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"url",
"description",
"content",
"updated_at"
],
"properties": {
"url": {
"type": "string",
"description": "The article's public link."
},
"title": {
"type": "string",
"description": "The article's title."
},
"content": {
"type": "string",
"description": "The article text to answer from."
},
"updated_at": {
"type": "string",
"description": "When the article last changed."
},
"description": {
"type": "string",
"description": "A one-line summary."
}
},
"additionalProperties": false
},
"description": "The matching articles."
},
"help_center_url": {
"type": "string",
"description": "The help center, for questions no article answers."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "hypd_search_help",
"title": "Search the HYPD help center",
"description": "Searches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privacy and data access, what HYPD can do, and setting HYPD up in Claude, ChatGPT or other AI clients. Returns the matching articles' text and links; answer from them and cite them. Not for advertising advice or the user's account data; use the platform tools for those.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"question"
],
"properties": {
"question": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "The user's question about HYPD, in their words, e.g. 'How do I connect my Google Ads account?'"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"articles",
"help_center_url",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How these results relate to the question."
},
"status": {
"enum": [
"ok",
"no_results"
],
"type": "string",
"description": "no_results when no article matched."
},
"articles": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"url",
"description",
"content",
"updated_at"
],
"properties": {
"url": {
"type": "string",
"description": "The article's public link."
},
"title": {
"type": "string",
"description": "The article's title."
},
"content": {
"type": "string",
"description": "The article text to answer from."
},
"updated_at": {
"type": "string",
"description": "When the article last changed."
},
"description": {
"type": "string",
"description": "A one-line summary."
}
},
"additionalProperties": false
},
"description": "The matching articles."
},
"help_center_url": {
"type": "string",
"description": "The help center, for questions no article answers."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search the HYPD help center",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Shows the user the accounts they have selected in HYPD across every connected platform, with the login that connected each and which accept changes, and returns how many there are and sources_url, the HYPD page where the user connects platforms and selects accounts. Use it when the user asks which accounts are connected to HYPD or wants to manage their connections. When a task needs accounts the user has not named, set can_pick, purpose and platforms, make it your turn's last tool call and stop: the user's pick arrives as their next message. Clients that render MCP Apps show a table with a button to that page, so do not repeat the accounts. Take the ids other tools need from their own list tools. If you see no table and no account list, give the count and sources_url as a link.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
can_pick
Show checkboxes so the user picks the accounts for a task. Their pick arrives as their next message.
Clear enough to supply this argument.
platforms
The platforms the table starts on, e.g. the ad platforms for a spend check. The user can turn others on. Default: all.
Clear enough to supply this argument.
purpose
What the pick is for, completing "Pick the accounts for ...", e.g. "the spend waste check".
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "hypd_show_connected_accounts",
"title": "Show connected accounts",
"description": "Shows the user the accounts they have selected in HYPD across every connected platform, with the login that connected each and which accept changes, and returns how many there are and sources_url, the HYPD page where the user connects platforms and selects accounts. Use it when the user asks which accounts are connected to HYPD or wants to manage their connections. When a task needs accounts the user has not named, set can_pick, purpose and platforms, make it your turn's last tool call and stop: the user's pick arrives as their next message. Clients that render MCP Apps show a table with a button to that page, so do not repeat the accounts. Take the ids other tools need from their own list tools. If you see no table and no account list, give the count and sources_url as a link.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"purpose": {
"type": "string",
"maxLength": 120,
"description": "What the pick is for, completing \"Pick the accounts for ...\", e.g. \"the spend waste check\"."
},
"can_pick": {
"type": "boolean",
"description": "Show checkboxes so the user picks the accounts for a task. Their pick arrives as their next message."
},
"platforms": {
"type": "array",
"items": {
"enum": [
"google_ads",
"google_merchant_center",
"google_analytics",
"google_search_console",
"google_tag_manager",
"meta_ads",
"microsoft_ads",
"linkedin_ads",
"tiktok_ads"
],
"type": "string"
},
"description": "The platforms the table starts on, e.g. the ad platforms for a spend check. The user can turn others on. Default: all."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"selected_count",
"sources_url",
"total_count"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "string"
}
},
"next_step": {
"type": "string"
},
"planNotice": {
"type": "string"
},
"sources_url": {
"type": "string"
},
"total_count": {
"type": "number"
},
"selected_count": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Show connected accounts",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Lists the accounts the user has selected in HYPD on every connected platform, with the id that platform's tools take: googleAdsId (Google Ads), merchantCenterId (Merchant Center), propertyId (Google Analytics), siteUrl (Search Console), accountId and containerId (Tag Manager), adAccountId (Meta Ads), accountId (Microsoft Ads, LinkedIn Ads, TikTok Ads). Call it before other tools to find accounts and their ids; set platforms to list only some. Each platform's state is ready, unavailable (try again), or missing_scope (this client's HYPD connection has no Google Ads access). An empty list means nothing is connected or selected there; planNotice then says why with a link, so show it to the user. Rows are as of HYPD's last sync: an item added on the platform since then appears once the user refreshes it on /sources.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platforms
Only these platforms. Default: all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "hypd_list_connected_accounts",
"title": "List connected accounts and ids",
"description": "Lists the accounts the user has selected in HYPD on every connected platform, with the id that platform's tools take: googleAdsId (Google Ads), merchantCenterId (Merchant Center), propertyId (Google Analytics), siteUrl (Search Console), accountId and containerId (Tag Manager), adAccountId (Meta Ads), accountId (Microsoft Ads, LinkedIn Ads, TikTok Ads). Call it before other tools to find accounts and their ids; set platforms to list only some. Each platform's state is ready, unavailable (try again), or missing_scope (this client's HYPD connection has no Google Ads access). An empty list means nothing is connected or selected there; planNotice then says why with a link, so show it to the user. Rows are as of HYPD's last sync: an item added on the platform since then appears once the user refreshes it on /sources.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"platforms": {
"type": "array",
"items": {
"enum": [
"google_ads",
"google_merchant_center",
"google_analytics",
"google_search_console",
"google_tag_manager",
"meta_ads",
"microsoft_ads",
"linkedin_ads",
"tiktok_ads"
],
"type": "string"
},
"description": "Only these platforms. Default: all."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"platforms"
],
"properties": {
"platforms": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"state",
"accounts"
],
"properties": {
"state": {
"enum": [
"ready",
"missing_scope",
"unavailable"
],
"type": "string"
},
"accounts": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"platform": {
"enum": [
"google_ads",
"google_merchant_center",
"google_analytics",
"google_search_console",
"google_tag_manager",
"meta_ads",
"microsoft_ads",
"linkedin_ads",
"tiktok_ads"
],
"type": "string"
},
"truncated": {
"type": "boolean"
},
"planNotice": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"annotations": {
"title": "List connected accounts and ids",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Shows the user HYPD's getting started steps: connecting an ad platform and selecting an account, then picking a first prompt from the prompt library. Use it when init says so, and whenever the user asks how to get started with HYPD, about onboarding or about their setup steps. Clients that render MCP Apps show the steps with a button each: a click sends that step's prompt as the user's next message, or opens the HYPD app. There, say only that the steps are shown above: do not repeat them and do not run a step before the user clicks it. Elsewhere, list the steps with their prompts and links.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations100/100
All four behavior hints are declared.
{
"title": "Getting started with HYPD",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
Output schema67/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"done_count",
"step_count"
],
"properties": {
"done_count": {
"type": "number",
"description": "Steps the user has completed."
},
"step_count": {
"type": "number",
"description": "Steps in total."
}
},
"description": "Counts only. The steps, with their prompts and links, go to the widget; the text content lists them for clients that show no widget.",
"additionalProperties": false
}
Original tool metadata
{
"name": "hypd_show_getting_started",
"title": "Getting started with HYPD",
"description": "Shows the user HYPD's getting started steps: connecting an ad platform and selecting an account, then picking a first prompt from the prompt library. Use it when init says so, and whenever the user asks how to get started with HYPD, about onboarding or about their setup steps. Clients that render MCP Apps show the steps with a button each: a click sends that step's prompt as the user's next message, or opens the HYPD app. There, say only that the steps are shown above: do not repeat them and do not run a step before the user clicks it. Elsewhere, list the steps with their prompts and links.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"done_count",
"step_count"
],
"properties": {
"done_count": {
"type": "number",
"description": "Steps the user has completed."
},
"step_count": {
"type": "number",
"description": "Steps in total."
}
},
"description": "Counts only. The steps, with their prompts and links, go to the widget; the text content lists them for clients that show no widget.",
"additionalProperties": false
},
"annotations": {
"title": "Getting started with HYPD",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description85/100
Shows the user HYPD's prompt library: ready-made prompts for audits, optimizations, reports and plans on their connected platforms. Use it when the user wants to browse or pick a ready-made prompt, or asks what HYPD can do without a task in mind. category, platforms and query set where the table opens. Clients that render MCP Apps show a table with Run and Preview per prompt: make it your turn's last tool call and stop, since a prompt the user runs arrives as their next message, and do not list the prompts. Elsewhere, list the keys and titles and fetch the chosen one with prompt_templates_get.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
category
The category the table starts on. Default: all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platforms
The platforms the table starts on, e.g. meta for a Meta task. Default: all.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
A search over titles and tags the table starts with.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"name": "hypd_show_prompt_library",
"title": "Show prompt library",
"description": "Shows the user HYPD's prompt library: ready-made prompts for audits, optimizations, reports and plans on their connected platforms. Use it when the user wants to browse or pick a ready-made prompt, or asks what HYPD can do without a task in mind. category, platforms and query set where the table opens. Clients that render MCP Apps show a table with Run and Preview per prompt: make it your turn's last tool call and stop, since a prompt the user runs arrives as their next message, and do not list the prompts. Elsewhere, list the keys and titles and fetch the chosen one with prompt_templates_get.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"query": {
"type": "string",
"maxLength": 120,
"description": "A search over titles and tags the table starts with."
},
"category": {
"enum": [
"create",
"plan",
"optimize",
"analyze",
"audit",
"troubleshoot",
"report",
"prospecting"
],
"type": "string",
"description": "The category the table starts on. Default: all."
},
"platforms": {
"type": "array",
"items": {
"enum": [
"googleads",
"seo",
"meta",
"merchant",
"ga4"
],
"type": "string"
},
"description": "The platforms the table starts on, e.g. meta for a Meta task. Default: all."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"prompt_count",
"total_count"
],
"properties": {
"prompts": {
"type": "array",
"items": {
"type": "string"
}
},
"next_step": {
"type": "string"
},
"total_count": {
"type": "number"
},
"prompt_count": {
"type": "number"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Show prompt library",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description88/100
Shows the user's HYPD invite link and how many of the people they invited have set up HYPD. Use it when a tool result mentions it, or when the user asks about inviting friends or colleagues to HYPD. Clients that render MCP Apps show it as a card with a button that copies the link.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
{
"name": "hypd_show_invite",
"title": "Invite friends to HYPD",
"description": "Shows the user's HYPD invite link and how many of the people they invited have set up HYPD. Use it when a tool result mentions it, or when the user asks about inviting friends or colleagues to HYPD. Clients that render MCP Apps show it as a card with a button that copies the link.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"done",
"eligible",
"target"
],
"properties": {
"done": {
"type": "number"
},
"target": {
"type": "number"
},
"eligible": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Invite friends to HYPD",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description79/100
Read eligible Selected Accounts for optional prompt context across Google Ads, Merchant Center, GA4, Meta Ads and Microsoft Ads. Does not fetch performance data or change selection.
Describe the returned information so the agent knows whether it will answer the request.
Inputs0/100
0 of 1 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values.
contextKey
Not provided
Missing description. Explain what this value means and how to supply it.
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01Search the Meta Ad LibrarySearch the public Meta Ad Library (Facebook and Instagram) by keyword to find live and past ads across advertisers, for competitor and market research.
02Search the HYPD help centerSearches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privac…
03Find Meta Ad Library advertisersResolve a brand or company name to its Meta Ad Library advertiser page id(s) — the entry point for pulling a specific competitor's ads.
04Audit a landing page (instant)Render a single landing page URL in a real browser and return the JavaScript-rendered DOM, HTTP status, redirect chain and server response timings.
05Audit a landing page (Lighthouse)Run a Lighthouse audit on a single landing page URL using Google data: returns Performance, Accessibility, and Best Practices scores with their underlying me…
Want to run these tasks against your MCP server with us?
HYPD AI for Paid Ads & Analytics setup, tools, quality score, publishing readiness, and alternatives.
How do I add HYPD AI for Paid Ads & Analytics to Claude, ChatGPT, or Cursor?
Add HYPD AI for Paid Ads & Analytics to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://mcp.hypd.ai/mcp/claude.
Is HYPD AI for Paid Ads & Analytics MCP ready for ChatGPT and Claude?
As of November 17, 2026, HYPD AI for Paid Ads & Analytics scores 90/100 on Manufact's MCP publishing checklist. The scan does not yet meet ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is HYPD AI for Paid Ads & Analytics's MCP tool documentation?
As of November 17, 2026, HYPD AI for Paid Ads & Analytics scores 88/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 146 of 146 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to HYPD AI for Paid Ads & Analytics?
As of November 17, 2026, alternatives to HYPD AI for Paid Ads & Analytics in marketing-seo on the Manufact MCP leaderboard include Notra, BulkPublish, Fuxux, HYPD AI for Ad Explorer, and HYPD AI for Ad Library.
How can HYPD AI for Paid Ads & Analytics improve its MCP documentation?
hypd_workspace_get_prompt_favorites is the lowest-scoring reviewed tool at 59/100. 0 of 1 inputs have descriptions. Add descriptions to the missing inputs, including where to obtain IDs and how to supply values. Open its review for feedback and a copyable fix prompt, then rerun the documentation review after updating your tool metadata.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.