MCP tool
forecast_search_performance
Read Google Ads v25 keyword performance estimates for an explicit budget, flight, native geo and language references, match types and bidding strategy. This stateless planning query creates no provider campaign and enables no spend. Live calls require verified supplier authority. Google does not accept campaign negatives, network controls or a selected custom conversion goal for this endpoint; acknowledge those limitations explicitly. Clicks, conversions and cost are returned only when the provider supplies them. Missing metrics stay absent or null; this result does not claim impressions, reach, frequency or CPM. Sandbox estimates are clearly labeled modeled. The API supplies its own request clock; callers cannot override asOf.
Input
Pass fields from this schema as the tool arguments. Runtime ownership, product scope and readiness checks still apply.
Input JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"adapterKey": {
"type": "string",
"const": "google-ads"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": false
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"keywords": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"matchType": {
"type": "string",
"enum": [
"exact",
"phrase",
"broad"
]
}
},
"required": [
"text",
"matchType"
],
"additionalProperties": false
}
},
"geoTargetConstants": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^geoTargetConstants\\/\\d+$"
}
},
"languageConstants": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^languageConstants\\/\\d+$"
}
},
"bidding": {
"oneOf": [
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "manual-cpc"
},
"maxCpcBidMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"strategy",
"maxCpcBidMinor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "maximize-clicks"
},
"maxCpcBidMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"strategy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "maximize-conversions"
}
},
"required": [
"strategy"
],
"additionalProperties": false
}
]
},
"acknowledgedLimitations": {
"type": "boolean",
"const": true
}
},
"required": [
"adapterKey",
"budget",
"startDate",
"endDate",
"keywords",
"geoTargetConstants",
"languageConstants",
"bidding",
"acknowledgedLimitations"
],
"additionalProperties": false
}REST mapping and authority
The tool wraps this REST endpoint. The mapping identifies path/query/body transformations and approval or idempotency headers.
Request contract
{
"method": "POST",
"path": "/api/v1/planning/provider-forecast",
"pathFields": [],
"pathSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"pathEncoding": "encodeURIComponent for each path field",
"governedAction": null,
"headers": {},
"bodySchema": {
"type": "object",
"properties": {
"adapterKey": {
"type": "string",
"const": "google-ads"
},
"budget": {
"type": "object",
"properties": {
"amountMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
}
},
"required": [
"amountMinor",
"currency"
],
"additionalProperties": false
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"keywords": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"matchType": {
"type": "string",
"enum": [
"exact",
"phrase",
"broad"
]
}
},
"required": [
"text",
"matchType"
],
"additionalProperties": false
}
},
"geoTargetConstants": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^geoTargetConstants\\/\\d+$"
}
},
"languageConstants": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^languageConstants\\/\\d+$"
}
},
"bidding": {
"oneOf": [
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "manual-cpc"
},
"maxCpcBidMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"strategy",
"maxCpcBidMinor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "maximize-clicks"
},
"maxCpcBidMinor": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"strategy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"const": "maximize-conversions"
}
},
"required": [
"strategy"
],
"additionalProperties": false
}
]
},
"acknowledgedLimitations": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false,
"required": [
"adapterKey",
"budget",
"startDate",
"endDate",
"keywords",
"geoTargetConstants",
"languageConstants",
"bidding",
"acknowledgedLimitations"
]
},
"responseMapping": "REST JSON is returned as MCP structuredContent and a compatibility text block; privacy-sensitive tools validate their output schema."
}Output
This is the registered MCP output envelope. Nested fields are only modeled where the schema explicitly defines them.
Output JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": {}
}Safety annotations
MCP annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}Annotations help a client present the tool. The API independently enforces authorization and exact action approvals. Error and retry guidance →