@soku-ai/cli 0.1.0-alpha.1 → 0.1.0-alpha.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/auth/device.d.ts +9 -0
- package/dist/auth/device.d.ts.map +1 -1
- package/dist/auth/device.js +6 -1
- package/dist/auth/device.js.map +1 -1
- package/dist/commands/ads.d.ts +32 -0
- package/dist/commands/ads.d.ts.map +1 -0
- package/dist/commands/ads.js +752 -0
- package/dist/commands/ads.js.map +1 -0
- package/dist/commands/auth.d.ts +2 -0
- package/dist/commands/auth.d.ts.map +1 -1
- package/dist/commands/auth.js +28 -7
- package/dist/commands/auth.js.map +1 -1
- package/dist/commands/automation.d.ts +80 -0
- package/dist/commands/automation.d.ts.map +1 -0
- package/dist/commands/automation.js +213 -0
- package/dist/commands/automation.js.map +1 -0
- package/dist/commands/brand-skill.d.ts +72 -0
- package/dist/commands/brand-skill.d.ts.map +1 -0
- package/dist/commands/brand-skill.js +351 -0
- package/dist/commands/brand-skill.js.map +1 -0
- package/dist/commands/brand.d.ts.map +1 -1
- package/dist/commands/brand.js +59 -1
- package/dist/commands/brand.js.map +1 -1
- package/dist/commands/call.d.ts.map +1 -1
- package/dist/commands/call.js +6 -3
- package/dist/commands/call.js.map +1 -1
- package/dist/commands/context.d.ts +23 -0
- package/dist/commands/context.d.ts.map +1 -0
- package/dist/commands/context.js +291 -0
- package/dist/commands/context.js.map +1 -0
- package/dist/commands/files.d.ts +10 -0
- package/dist/commands/files.d.ts.map +1 -0
- package/dist/commands/files.js +48 -0
- package/dist/commands/files.js.map +1 -0
- package/dist/commands/generated.d.ts +24 -3
- package/dist/commands/generated.d.ts.map +1 -1
- package/dist/commands/generated.js +97 -10
- package/dist/commands/generated.js.map +1 -1
- package/dist/commands/memory.d.ts +18 -0
- package/dist/commands/memory.d.ts.map +1 -0
- package/dist/commands/memory.js +70 -0
- package/dist/commands/memory.js.map +1 -0
- package/dist/commands/review.d.ts.map +1 -1
- package/dist/commands/review.js +46 -2
- package/dist/commands/review.js.map +1 -1
- package/dist/commands/seo-hosting.d.ts +107 -0
- package/dist/commands/seo-hosting.d.ts.map +1 -0
- package/dist/commands/seo-hosting.js +499 -0
- package/dist/commands/seo-hosting.js.map +1 -0
- package/dist/commands/skill.d.ts +50 -6
- package/dist/commands/skill.d.ts.map +1 -1
- package/dist/commands/skill.js +120 -56
- package/dist/commands/skill.js.map +1 -1
- package/dist/commands/update.d.ts +23 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +345 -0
- package/dist/commands/update.js.map +1 -0
- package/dist/commands/workspace.d.ts +4 -0
- package/dist/commands/workspace.d.ts.map +1 -0
- package/dist/commands/workspace.js +132 -0
- package/dist/commands/workspace.js.map +1 -0
- package/dist/config.d.ts +5 -4
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +5 -7
- package/dist/config.js.map +1 -1
- package/dist/generated/capabilities.json +291 -30
- package/dist/http/client.d.ts.map +1 -1
- package/dist/http/client.js +74 -16
- package/dist/http/client.js.map +1 -1
- package/dist/index.js +35 -3
- package/dist/index.js.map +1 -1
- package/dist/output/envelope.d.ts +5 -0
- package/dist/output/envelope.d.ts.map +1 -1
- package/dist/output/envelope.js +101 -2
- package/dist/output/envelope.js.map +1 -1
- package/dist/output/unwrap.d.ts.map +1 -1
- package/dist/output/unwrap.js +18 -1
- package/dist/output/unwrap.js.map +1 -1
- package/dist/skills/unzip.d.ts +1 -1
- package/dist/skills/unzip.js +1 -1
- package/dist/update-check.d.ts +0 -1
- package/dist/update-check.d.ts.map +1 -1
- package/dist/update-check.js +4 -54
- package/dist/update-check.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +7 -4
- package/postinstall.cjs +85 -0
- package/skills/soku/SKILL.md +254 -18
- package/README.md +0 -91
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
"namespace": "ads",
|
|
6
6
|
"action": "gaql_search",
|
|
7
7
|
"description": "Realtime Google Ads GAQL fallback for native fields or segments not covered by cached query_* actions; no business-layer CPA/ROAS semantics.",
|
|
8
|
-
"long_description": "FALLBACK PATH for Google-native ads exploration.\n\nPrimary use:\nRealtime GAQL search for fields, segments, or dimension combinations that are not exposed by cached query_single_dimension or query_multi_dimension.\n\nUse when:\n- list_dimensions does not expose the field or segment the user needs.\n- query_multi_dimension returns unsupported_dimension_combination and a GAQL fallback is acceptable.\n- You need Google-native resource fields, raw.segments.*, or raw.
|
|
9
|
-
"
|
|
8
|
+
"long_description": "FALLBACK PATH for Google-native ads exploration.\n\nPrimary use:\nRealtime GAQL search for fields, segments, or dimension combinations that are not exposed by cached query_single_dimension or query_multi_dimension.\n\nUse when:\n- list_dimensions does not expose the field or segment the user needs.\n- query_multi_dimension returns unsupported_dimension_combination and a GAQL fallback is acceptable.\n- You need Google-native resource fields, raw.segments.*, raw.metrics.*, or deep attribute paths such as raw.ad_group_ad.ad.responsive_search_ad.headlines.\n\nDo not use when:\n- Cached business-layer analytics can answer the question. Use query_single_dimension or query_multi_dimension.\n- The user needs CPA, CPP, ROAS, Reg Rate, Pur Rate, or cg.{slug}.* fan-out. Use query_single_dimension.\n- The platform is Meta. This action is Google-only.\n\nWorkflow:\n1. Call list_dimensions first to confirm cached analytics cannot satisfy the query.\n2. Call get_resource_metadata if you do not know selectable/filterable/sortable Google fields for the target resource.\n3. Call this action with account_id, dimensions[], metrics[], optional resource_name, filters, date_range, order_by, limit, and mode. Set resource_name when the select list mixes the root resource with selectable-with related resources, such as FROM asset_group_asset selecting asset.* fields.\n\nOutput semantics:\n- Returns translated Google Ads query text in query.\n- columns contains normalized field arrays; rows may also be present for convenience.\n- account.data_freshness is realtime call time, not Parquet sync time.\n- No mapping-aware derived metrics or conversion-group fan-out are computed.",
|
|
9
|
+
"mode": "read",
|
|
10
10
|
"priority": "advanced",
|
|
11
11
|
"requires_review": false,
|
|
12
12
|
"freshness_kind": "realtime",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"name": "dimensions",
|
|
28
28
|
"type": "list",
|
|
29
29
|
"required": true,
|
|
30
|
-
"description": "Dimension fields. Use L1.5 slugs such as date or campaign, or raw
|
|
30
|
+
"description": "Dimension fields. Use L1.5 slugs such as date or campaign, or raw.<resource>.<field>[.<subfield>...] fields discovered via get_resource_metadata."
|
|
31
31
|
},
|
|
32
32
|
{
|
|
33
33
|
"name": "metrics",
|
|
@@ -35,11 +35,17 @@
|
|
|
35
35
|
"required": true,
|
|
36
36
|
"description": "Metric fields. Use L1.5 slugs such as clicks or cost, or raw.metrics.X fields discovered via get_resource_metadata."
|
|
37
37
|
},
|
|
38
|
+
{
|
|
39
|
+
"name": "resource_name",
|
|
40
|
+
"type": "string",
|
|
41
|
+
"required": false,
|
|
42
|
+
"description": "Optional explicit GAQL FROM resource, e.g. ad_group_ad or asset_group_asset. Use when dimensions include selectable-with fields from related resources."
|
|
43
|
+
},
|
|
38
44
|
{
|
|
39
45
|
"name": "date_range",
|
|
40
|
-
"type": "
|
|
46
|
+
"type": "list",
|
|
41
47
|
"required": false,
|
|
42
|
-
"description": "
|
|
48
|
+
"description": "Two-item [date_start, date_end] array in YYYY-MM-DD format. Required for metric or segment queries; optional for pure metadata-style entity reads. Top-level date_start/date_end are also accepted for compatibility."
|
|
43
49
|
},
|
|
44
50
|
{
|
|
45
51
|
"name": "filters",
|
|
@@ -78,8 +84,8 @@
|
|
|
78
84
|
"namespace": "ads",
|
|
79
85
|
"action": "get_resource_metadata",
|
|
80
86
|
"description": "Discover selectable, filterable, and sortable Google Ads fields for a GAQL resource before building gaql_search raw.* inputs.",
|
|
81
|
-
"long_description": "FALLBACK PATH companion to gaql_search.\n\nPrimary use:\nGoogle Ads field discovery for a single GAQL resource such as campaign, ad_group, ad_group_criterion, or customer.\n\nUse when:\n- You plan to call gaql_search and need to know which native Google Ads fields exist.\n- You need to validate whether a field is selectable, filterable, or sortable.\n- A previous gaql_search failed because a raw field was unknown or not allowed.\n\nDo not use when:\n- You need cached business-layer analytics dimensions. Use list_dimensions.\n- You need conversion group business semantics. Use list_conversion_groups.\n- The platform is Meta. This action is Google-only.\n\nWorkflow:\n1. Choose the Google Ads GAQL resource name.\n2. Call this action to inspect fields.\n3. Use returned field names in gaql_search via raw.segments.X or raw.metrics.X
|
|
82
|
-
"
|
|
87
|
+
"long_description": "FALLBACK PATH companion to gaql_search.\n\nPrimary use:\nGoogle Ads field discovery for a single GAQL resource such as campaign, ad_group, ad_group_criterion, or customer.\n\nUse when:\n- You plan to call gaql_search and need to know which native Google Ads fields exist.\n- You need to validate whether a field is selectable, filterable, or sortable.\n- A previous gaql_search failed because a raw field was unknown or not allowed.\n\nDo not use when:\n- You need cached business-layer analytics dimensions. Use list_dimensions.\n- You need conversion group business semantics. Use list_conversion_groups.\n- The platform is Meta. This action is Google-only.\n\nWorkflow:\n1. Choose the Google Ads GAQL resource name.\n2. Call this action to inspect fields.\n3. Use returned field names in gaql_search via raw.<resource>.<field>[.<subfield>...], raw.segments.X, or raw.metrics.X; pass resource_name to gaql_search when selecting related resources returned through selectable_with.\n\nOutput semantics:\n- selectable fields can be requested in gaql_search dimensions or metrics.\n- filterable fields can be used in gaql_search filters.\n- sortable fields can be used in gaql_search order_by.\n- data_type is the Google Ads API field data type.",
|
|
88
|
+
"mode": "read",
|
|
83
89
|
"priority": "advanced",
|
|
84
90
|
"requires_review": false,
|
|
85
91
|
"freshness_kind": "realtime",
|
|
@@ -115,7 +121,7 @@
|
|
|
115
121
|
"action": "list_ad_accounts",
|
|
116
122
|
"description": "Discover brand-granted Google/Meta ad accounts; returns account_id values required by later ads queries and ads-ops actions.",
|
|
117
123
|
"long_description": "Primary use:\nAccount discovery for the current brand. Use the returned account_id values as the only valid account_id inputs for later ads analytics or ads-ops calls.\n\nUse when:\n- The user did not provide an account_id.\n- The user asks which ad accounts are available.\n- You need to choose a Google or Meta account before querying metrics or running ads-ops actions.\n\nDo not use when:\n- You already have an account_id from this response in the same workflow.\n- You need campaign/ad/keyword metrics. Use list_dimensions plus query_* instead.\n\nWorkflow:\n1. Call this action, optionally filtering by platform.\n2. Pick one row's account_id and platform.\n3. Reuse that account_id in query_single_dimension, query_multi_dimension, gaql_search, get_resource_metadata, list_operation_records, or ads-ops actions.\n\nOutput semantics:\n- rows[].account_id is the external platform account id expected by later calls.\n- rows[].data_freshness is the latest completed ads sync run finish time for that account.\n\nConstraints:\n- Rows are filtered by ResourceBrandGrant for the sandbox brand.\n- An account absent from this response cannot be used in ads or ads-ops calls; the dispatcher returns 403.",
|
|
118
|
-
"
|
|
124
|
+
"mode": "read",
|
|
119
125
|
"priority": "supporting",
|
|
120
126
|
"requires_review": false,
|
|
121
127
|
"freshness_kind": "synced",
|
|
@@ -135,13 +141,50 @@
|
|
|
135
141
|
"action:ads/query_multi_dimension"
|
|
136
142
|
]
|
|
137
143
|
},
|
|
144
|
+
{
|
|
145
|
+
"id": "action:ads/list_brand_campaigns",
|
|
146
|
+
"namespace": "ads",
|
|
147
|
+
"action": "list_brand_campaigns",
|
|
148
|
+
"description": "List brand-visible campaigns for manually linking a campaign to a conversion group via set_conversion_group_manual_campaign.",
|
|
149
|
+
"long_description": "Primary use:\nFind candidate campaigns and their internal campaign_id when you need to manually include or exclude a campaign on a conversion group.\n\nOutput semantics:\n- campaigns[].campaign_id is the INTERNAL id required by set/clear_conversion_group_manual_campaign (not the platform id).\n- campaigns[].platform_campaign_id is the platform's campaign id.\n- source/included are always manual/true here; auto and excluded states only appear inside a group's resolved campaigns from list_conversion_groups.",
|
|
150
|
+
"mode": "read",
|
|
151
|
+
"priority": "supporting",
|
|
152
|
+
"requires_review": false,
|
|
153
|
+
"freshness_kind": "synced",
|
|
154
|
+
"input_params": [
|
|
155
|
+
{
|
|
156
|
+
"name": "platform",
|
|
157
|
+
"type": "string",
|
|
158
|
+
"required": false,
|
|
159
|
+
"description": "Optional platform filter (google/meta).",
|
|
160
|
+
"example": "google"
|
|
161
|
+
},
|
|
162
|
+
{
|
|
163
|
+
"name": "search",
|
|
164
|
+
"type": "string",
|
|
165
|
+
"required": false,
|
|
166
|
+
"description": "Optional name/id substring filter."
|
|
167
|
+
},
|
|
168
|
+
{
|
|
169
|
+
"name": "limit",
|
|
170
|
+
"type": "integer",
|
|
171
|
+
"required": false,
|
|
172
|
+
"description": "Max rows (default 100, max 500)."
|
|
173
|
+
}
|
|
174
|
+
],
|
|
175
|
+
"output_shape": "{\"campaigns\": [{\"campaign_id\": \"456\", \"platform_campaign_id\": \"789\", \"name\": \"Holiday Sale\", \"platform\": \"google\", \"source\": \"manual\", \"included\": true}]}",
|
|
176
|
+
"see_also": [
|
|
177
|
+
"action:ads/set_conversion_group_manual_campaign",
|
|
178
|
+
"action:ads/list_conversion_groups"
|
|
179
|
+
]
|
|
180
|
+
},
|
|
138
181
|
{
|
|
139
182
|
"id": "action:ads/list_conversion_actions",
|
|
140
183
|
"namespace": "ads",
|
|
141
184
|
"action": "list_conversion_actions",
|
|
142
185
|
"description": "List synced platform conversion actions that can be mapped into conversion groups for the caller's brand-granted ad accounts.",
|
|
143
186
|
"long_description": "Primary use:\nConversion action candidate discovery for maintaining conversion_group rules. Use this action when you need the platform conversion_action_id values that can be bound to a conversion group.\n\nUse when:\n- You are preparing to create or update conversion_group rules.\n- You need to know whether a platform conversion action is already mapped.\n- You need account-scoped conversion action metadata such as platform, customer_id, category, type, or status.\n\nDo not use when:\n- You need business conversion group slugs or derived metric labels. Use list_conversion_groups.\n- You need live platform inventory from ads-ops. This action returns synced Nex data limited to the current brand's granted ad accounts.\n\nOutput semantics:\n- conversion_actions[].account_id is the internal ad account id used by conversion mapping rules.\n- conversion_actions[].conversion_action_id is the platform action id used by rules.\n- conversion_actions[].data_freshness is the latest completed ads sync run finish time for the action's account.\n- mapped_to lists conversion_group slugs that already include the action.",
|
|
144
|
-
"
|
|
187
|
+
"mode": "read",
|
|
145
188
|
"priority": "supporting",
|
|
146
189
|
"requires_review": false,
|
|
147
190
|
"freshness_kind": "synced",
|
|
@@ -159,13 +202,38 @@
|
|
|
159
202
|
"action:ads/list_conversion_groups"
|
|
160
203
|
]
|
|
161
204
|
},
|
|
205
|
+
{
|
|
206
|
+
"id": "action:ads/list_conversion_goals",
|
|
207
|
+
"namespace": "ads",
|
|
208
|
+
"action": "list_conversion_goals",
|
|
209
|
+
"description": "List platform conversion goals visible to the brand. A goal is the bridge that links a conversion group to the campaigns optimizing for it.",
|
|
210
|
+
"long_description": "Primary use:\nDiscover platform conversion goals (Google/Meta) that can be linked to a conversion group via bind_conversion_group_goal. A goal carries the campaign_ids that optimize for it, so linking a goal is how a group inherits those campaigns.\n\nOutput semantics:\n- conversion_goals[].id is the internal goal id used by bind/unbind_conversion_group_goal.\n- conversion_goals[].conversion_action_ids are platform action ids the goal covers.\n- conversion_goals[].campaign_ids are platform campaign ids optimizing for the goal. Known limitation: Google does not expose a campaign->custom goal edge so this may be empty for Google goals; Meta only resolves campaigns bound via custom_conversion_id.",
|
|
211
|
+
"mode": "read",
|
|
212
|
+
"priority": "supporting",
|
|
213
|
+
"requires_review": false,
|
|
214
|
+
"freshness_kind": "synced",
|
|
215
|
+
"input_params": [
|
|
216
|
+
{
|
|
217
|
+
"name": "platform",
|
|
218
|
+
"type": "string",
|
|
219
|
+
"required": false,
|
|
220
|
+
"description": "Optional platform filter. Use google or meta; omit to list all.",
|
|
221
|
+
"example": "google"
|
|
222
|
+
}
|
|
223
|
+
],
|
|
224
|
+
"output_shape": "{\"conversion_goals\": [{\"id\": 12, \"platform\": \"google\", \"account_id\": 5, \"platform_goal_id\": \"abc\", \"name\": \"Purchase\", \"type\": \"custom_conversion_goal\", \"status\": \"ENABLED\", \"conversion_action_ids\": [\"act_purchase\"], \"campaign_ids\": [\"123\"], \"last_synced_at\": \"ISO\"}]}",
|
|
225
|
+
"see_also": [
|
|
226
|
+
"action:ads/list_conversion_groups",
|
|
227
|
+
"action:ads/bind_conversion_group_goal"
|
|
228
|
+
]
|
|
229
|
+
},
|
|
162
230
|
{
|
|
163
231
|
"id": "action:ads/list_conversion_groups",
|
|
164
232
|
"namespace": "ads",
|
|
165
233
|
"action": "list_conversion_groups",
|
|
166
234
|
"description": "Discover conversion group slugs and derived CPA/ROAS labels needed for cg.{slug}.* columns in query_single_dimension. Scoped to the caller's brand.",
|
|
167
|
-
"long_description": "Primary use:\nConversion Mapping Group discovery for business metrics such as CPA, CPP, ROAS, Reg Rate, and Pur Rate. Use the returned group slugs to build legal cg.{slug}.* column references for query_single_dimension.\n\nUse when:\n- The user asks for CPA, CPP, ROAS, registration rate, purchase rate, or other mapped conversion metrics.\n- You plan to request or interpret cg.{slug}.* fan-out columns.\n- You need to know the default attribution_window, time_field, value_field, or display labels for conversion-derived metrics.\n\nDo not use when:\n- You only need platform raw metrics such as clicks, impressions, spend_micros, ctr, or conversions.\n- You are using query_multi_dimension. Multi-dimensional queries do not support conversion-group fan-out or mapping-aware derived metrics.\n\nWorkflow:\n1. Call list_dimensions to confirm the dimension supports cg fan-out.\n2. Call this action to get legal group slugs, labels, metadata, and version tokens.\n3. Call query_single_dimension with cg.{slug}.* columns implied by the selected metrics.\n\nOutput semantics:\n- groups[].slug is the only legal slug in cg.{slug}.* column references.\n- groups[].brand_id echoes the caller's brand; same slug can mean a different configuration in another brand of the same org.\n- groups[].version is an opaque precondition token for conversion_group write actions.\n- derived_metrics explains the display label and denominator/value semantics.\n- metadata is a customer-defined list of key/value/description fields for agent interpretation.\n- attribution_window is the group default unless query_single_dimension overrides it.\n- Admin-Web fields such as color, sort_order, owner_admin_user_id, and
|
|
168
|
-
"
|
|
235
|
+
"long_description": "Primary use:\nConversion Mapping Group discovery for business metrics such as CPA, CPP, ROAS, Reg Rate, and Pur Rate. Use the returned group slugs to build legal cg.{slug}.* column references for query_single_dimension.\n\nUse when:\n- The user asks for CPA, CPP, ROAS, registration rate, purchase rate, or other mapped conversion metrics.\n- You plan to request or interpret cg.{slug}.* fan-out columns.\n- You need to know the default attribution_window, time_field, value_field, or display labels for conversion-derived metrics.\n\nDo not use when:\n- You only need platform raw metrics such as clicks, impressions, spend_micros, ctr, or conversions.\n- You are using query_multi_dimension. Multi-dimensional queries do not support conversion-group fan-out or mapping-aware derived metrics.\n\nWorkflow:\n1. Call list_dimensions to confirm the dimension supports cg fan-out.\n2. Call this action to get legal group slugs, labels, metadata, and version tokens.\n3. Call query_single_dimension with cg.{slug}.* columns implied by the selected metrics.\n\nOutput semantics:\n- groups[].slug is the only legal slug in cg.{slug}.* column references.\n- groups[].brand_id echoes the caller's brand; same slug can mean a different configuration in another brand of the same org.\n- groups[].version is an opaque precondition token for conversion_group write actions.\n- derived_metrics explains the display label and denominator/value semantics.\n- metadata is a customer-defined list of key/value/description fields for agent interpretation.\n- attribution_window is the group default unless query_single_dimension overrides it.\n- Admin-Web fields such as color, sort_order, owner_admin_user_id, and level are intentionally not exposed.",
|
|
236
|
+
"mode": "read",
|
|
169
237
|
"priority": "supporting",
|
|
170
238
|
"requires_review": false,
|
|
171
239
|
"freshness_kind": "synced",
|
|
@@ -183,7 +251,7 @@
|
|
|
183
251
|
"action": "list_conversions",
|
|
184
252
|
"description": "Deprecated alias for list_conversion_groups. Returns conversion group business fields under rows for short-term compatibility.",
|
|
185
253
|
"long_description": "Deprecated compatibility alias.\n\nUse list_conversion_groups for new workflows. This action exists only so older agents that learned the legacy list_conversions name can still discover conversion group slugs and derived metric labels.\n\nOutput semantics:\n- rows[] contains conversion_group specs with the same field set as list_conversion_groups.groups[].\n- This action does not list platform conversion actions. Use list_conversion_actions for that.",
|
|
186
|
-
"
|
|
254
|
+
"mode": "read",
|
|
187
255
|
"priority": "supporting",
|
|
188
256
|
"requires_review": false,
|
|
189
257
|
"freshness_kind": "synced",
|
|
@@ -201,7 +269,7 @@
|
|
|
201
269
|
"action": "list_dimensions",
|
|
202
270
|
"description": "Discover cached ads dimensions, metrics, filters, and scope caveats before building query_single_dimension or query_multi_dimension calls.",
|
|
203
271
|
"long_description": "Primary use:\nSchema discovery for cached ads analytics. This is the primary way to learn which business-layer dimensions, metrics, filters, scopes, and Parquet-backed views can be queried.\n\nUse when:\n- Before the first query_single_dimension or query_multi_dimension call in a workflow.\n- You need valid dimension slugs such as account, date, campaign, adgroup, ad, keyword, search_term, device, country, language, landing_page, age_range, or gender.\n- You need filterable_fields, parent_dimensions, scope_caveat, or cg fan-out support.\n- You need to know which raw and derived metrics are available.\n\nDo not use when:\n- You need Google Ads native fields not listed here. Use get_resource_metadata then gaql_search.\n- You need conversion group slugs for cg.{slug}.* columns. Use list_conversion_groups.\n\nWorkflow:\n1. Call list_ad_accounts if account_id is unknown.\n2. Call this action to select dimensions, filters, and metrics.\n3. Use query_single_dimension for one dimension or mapping-aware metrics.\n4. Use query_multi_dimension for valid multi-dimensional raw breakdowns.\n\nOutput semantics:\n- dimensions[].name is the dimension slug to pass as dimension or dimensions[].\n- dimensions[].filterable_fields are the only supported filter keys for that dimension.\n- dimensions[].supports_cg_fanout tells whether cg.{slug}.* columns can be requested.\n- metrics[].slug is the metric name to read from query output columns.",
|
|
204
|
-
"
|
|
272
|
+
"mode": "read",
|
|
205
273
|
"priority": "supporting",
|
|
206
274
|
"requires_review": false,
|
|
207
275
|
"freshness_kind": "synced",
|
|
@@ -228,7 +296,7 @@
|
|
|
228
296
|
"action": "list_operation_records",
|
|
229
297
|
"description": "List Nex-side ads-ops action records for an account and date range; not Google Ads external change history.",
|
|
230
298
|
"long_description": "Primary use:\nAudit Nex-side ads-ops actions that were recorded for a specific ad account and date range. This helps explain what Nex or an agent attempted to change.\n\nUse when:\n- The user asks what actions Nex or an agent performed on an ad account.\n- You need before/after payloads for Nex-recorded ads-ops writes.\n- You need operator_user_id, operator_display_name, action_type, target entity, and timestamp for internal troubleshooting.\n\nDo not use when:\n- The user asks for Google's external account change history. Use ads-ops.get_change_history.\n- The user asks for analytics metrics. Use query_single_dimension or query_multi_dimension.\n\nWorkflow:\n1. Call list_ad_accounts if account_id is unknown.\n2. Call this action with platform, account_id, date_start, and date_end.\n3. Use page and page_size for pagination when the result is large.\n\nOutput semantics:\n- rows[] contains Nex internal action records, not platform-native history.\n- before and after are the recorded operation payload snapshots when available.\n- Operator email is never returned to avoid PII leakage; use operator_user_id and operator_display_name only.",
|
|
231
|
-
"
|
|
299
|
+
"mode": "read",
|
|
232
300
|
"priority": "supporting",
|
|
233
301
|
"requires_review": false,
|
|
234
302
|
"freshness_kind": "synced",
|
|
@@ -282,7 +350,7 @@
|
|
|
282
350
|
"action": "query_multi_dimension",
|
|
283
351
|
"description": "Cached ads breakdown across multiple dimensions; returns column-oriented raw platform metrics without CPA/ROAS or cg.{slug}.* fan-out.",
|
|
284
352
|
"long_description": "PRIMARY PATH for cached multi-dimensional breakdowns.\n\nPrimary use:\nMulti-dimensional reporting over synced Nex ads data, such as campaign x country or campaign x device. Use it when the user needs more than one group-by dimension.\n\nUse when:\n- The user asks for a breakdown by two or more supported dimensions.\n- The requested combination is valid according to the service viable-combo table.\n- Raw platform metrics are sufficient.\n\nDo not use when:\n- The user needs CPA, CPP, ROAS, Reg Rate, Pur Rate, or cg.{slug}.* columns. Use query_single_dimension.\n- A single dimension is enough. Use query_single_dimension for richer semantics.\n- The dimension combination is unsupported and must use Google-native fields. Use get_resource_metadata then gaql_search.\n\nWorkflow:\n1. Call list_ad_accounts if account_id is unknown.\n2. Call list_dimensions to choose legal dimension slugs and filters.\n3. Prefer the most specific child dimension; the handler may drop redundant parent dimensions and report that in notice.\n4. Call this action with platform, account_id, date range, and dimensions[].\n\nOutput semantics:\n- Returns column-oriented data. Read data.columns.<column>[i], not data.rows.\n- Only platform-raw conversion metrics are available.\n- requested_dimensions preserves the original request when normalization occurs.\n- notice describes dropped parent dimensions; unsupported combinations return 400 unsupported_dimension_combination with nearest viable combos and a GAQL fallback hint.\n- For id-keyed dimensions (campaign / account / adgroup / ad), the response includes both the raw id column (e.g., adset_id) and the resolved name column (e.g., adset_name) for agent display. Use the id column for filters / drills; use the name column for user-facing output.",
|
|
285
|
-
"
|
|
353
|
+
"mode": "read",
|
|
286
354
|
"priority": "primary",
|
|
287
355
|
"requires_review": false,
|
|
288
356
|
"freshness_kind": "synced",
|
|
@@ -358,8 +426,8 @@
|
|
|
358
426
|
"namespace": "ads",
|
|
359
427
|
"action": "query_single_dimension",
|
|
360
428
|
"description": "Primary cached ads analytics query for one dimension; returns column-oriented business metrics, derived metrics, and cg.{slug}.* conversion fan-out.",
|
|
361
|
-
"long_description": "PRIMARY PATH for cached ads analytics.\n\nPrimary use:\nSingle-dimension reporting over synced Nex business-layer ads data. Use this for
|
|
362
|
-
"
|
|
429
|
+
"long_description": "PRIMARY PATH for cached ads analytics.\n\nPrimary use:\nSingle-dimension reporting over synced Nex business-layer ads data. Use this for metrics report KPIs, campaign/ad/adgroup/keyword/search-term/device/country breakdowns, cross-platform-consistent metrics, and mapping-aware derived metrics.\n\nUse when:\n- The analysis has exactly one group-by dimension.\n- The user asks for CPA, CPP, ROAS, Reg Rate, Pur Rate, or cg.{slug}.* metrics.\n- The result should use Nex cached Parquet data and business semantics.\n\nDo not use when:\n- The user needs multiple group-by dimensions. Use query_multi_dimension.\n- The field or segment is not exposed by list_dimensions. Use get_resource_metadata then gaql_search for Google-native exploration.\n- The user needs write or mutation history. Use ads-ops or list_operation_records.\n\nWorkflow:\n1. Call list_ad_accounts if account_id is unknown.\n2. Call list_dimensions to choose a valid dimension, filters, and metrics.\n3. Call list_conversion_groups only if conversion-group fan-out or CPA/ROAS-like metrics are needed.\n4. Call this action with platform, account_id, date_start, date_end, and dimension.\n\nOutput semantics:\n- Returns column-oriented data. Read data.columns.<column>[i], not data.rows.\n- spend_micros and cpc_micros are micros; ctr is a 0-1 ratio.\n- scope_caveat explains aggregation limits for the selected scope.\n- mode=summary returns summary data such as top rows, totals, and p95 where supported.\n- truncated or warning means the agent must mention partial result limits.\n- For id-keyed dimensions (campaign / account / adgroup / ad), dimension_label is the resolved entity name (e.g., adset name for adgroup dimension); falls back to the platform id when the entity record is missing or has no name.",
|
|
430
|
+
"mode": "read",
|
|
363
431
|
"priority": "primary",
|
|
364
432
|
"requires_review": false,
|
|
365
433
|
"freshness_kind": "synced",
|
|
@@ -443,7 +511,7 @@
|
|
|
443
511
|
"action": "get_conversion_overview",
|
|
444
512
|
"description": "Cached GA4 key-event summary for a property over a date range; returns total key events, revenue, and top converting traffic sources.",
|
|
445
513
|
"long_description": "Primary use:\nConversion summary using GA4 v5+ key_events, together with the top sources that drove those events.\n\nUse when:\n- The user asks for total conversions or key events for a period.\n- The user asks which sources drove the most conversions.\n- You need a quick conversion + revenue snapshot without picking specific events.\n\nDo not use when:\n- The user needs event-level counts beyond conversions. Use list_events.\n- The user needs a daily key-event time series. Use get_daily_trend and read rows[].key_events.\n- The user needs per-page conversion breakdown. Use list_top_pages and read rows[].key_events.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date_start, date_end.\n\nOutput semantics:\n- overview.total_key_events sums property-level key_events for the range.\n- overview.total_revenue_micros is in micros.\n- overview.top_converting_sources has the same row shape as list_traffic_sources, sorted by key_events DESC and capped at 10.\n- Returns zeros and an empty top_converting_sources when the property has no synced data for the range.",
|
|
446
|
-
"
|
|
514
|
+
"mode": "read",
|
|
447
515
|
"priority": "primary",
|
|
448
516
|
"requires_review": false,
|
|
449
517
|
"freshness_kind": "synced",
|
|
@@ -484,7 +552,7 @@
|
|
|
484
552
|
"action": "get_daily_trend",
|
|
485
553
|
"description": "Cached GA4 daily KPI time series for a property over a date range; returns one row per day for charting and anomaly detection.",
|
|
486
554
|
"long_description": "Primary use:\nPer-day GA4 KPI time series for a property.\n\nUse when:\n- The user asks for a daily chart, week-over-week or day-over-day comparison, or anomaly check.\n- You need report_date x property-level metrics ordered by day.\n\nDo not use when:\n- The user needs a single aggregated snapshot. Use get_property_overview.\n- The user needs per-page, per-source, or per-event daily breakdown. This action does not split by dimension.\n- The user wants daily ad spend. Use ads.query_single_dimension with dimension=date.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date_start, date_end.\n\nOutput semantics:\n- rows[].report_date is ISO YYYY-MM-DD.\n- rows[].total_revenue_micros is in micros; rows[].bounce_rate is a 0-1 ratio; rows[].avg_session_duration_seconds is in seconds.\n- rows[].key_events replaces legacy 'conversions' (GA4 v5+).\n- Returns [] when the property has no synced data for the range.",
|
|
487
|
-
"
|
|
555
|
+
"mode": "read",
|
|
488
556
|
"priority": "primary",
|
|
489
557
|
"requires_review": false,
|
|
490
558
|
"freshness_kind": "synced",
|
|
@@ -518,13 +586,39 @@
|
|
|
518
586
|
"action:ga4/list_traffic_sources"
|
|
519
587
|
]
|
|
520
588
|
},
|
|
589
|
+
{
|
|
590
|
+
"id": "action:ga4/get_metadata",
|
|
591
|
+
"namespace": "ga4",
|
|
592
|
+
"action": "get_metadata",
|
|
593
|
+
"description": "Live GA4 Data API metadata discovery for one property; returns queryable dimensions and metrics, including custom definitions when GA4 exposes them.",
|
|
594
|
+
"long_description": "Primary use:\nDiscover valid GA4 Data API dimension and metric api_name values before calling ga4.run_report for fields outside the cached action set.\n\nUse when:\n- You need a GA4 dimension or metric that is not covered by fixed cached actions.\n- ga4.run_report returned ga4_invalid_query and you need valid selectable fields.\n- You need custom GA4 definitions exposed by the property metadata endpoint.\n\nDo not use when:\n- You only need Soku metric registry semantics. Use ga4.list_metrics.\n- You only need standard cached summaries, trends, pages, sources, or events.\n\nOutput semantics:\n- dimensions[].api_name and metrics[].api_name are the names accepted by run_report.\n- custom_definition=true means the field is property-specific.\n- This is live GA4 Data API metadata and requires a valid GA4 credential.",
|
|
595
|
+
"mode": "read",
|
|
596
|
+
"priority": "advanced",
|
|
597
|
+
"requires_review": false,
|
|
598
|
+
"freshness_kind": "realtime",
|
|
599
|
+
"input_params": [
|
|
600
|
+
{
|
|
601
|
+
"name": "property_id",
|
|
602
|
+
"type": "string",
|
|
603
|
+
"required": true,
|
|
604
|
+
"description": "Property id from list_properties.rows[].property_id. account_id is accepted as an alias.",
|
|
605
|
+
"example": "123456789"
|
|
606
|
+
}
|
|
607
|
+
],
|
|
608
|
+
"output_shape": "{\"property\": {\"property_id\": \"123456789\", \"data_freshness\": \"ISO\"}, \"dimensions\": [{\"api_name\": \"date\", \"ui_name\": \"Date\", \"custom_definition\": false, \"category\": \"Time\"}], \"metrics\": [{\"api_name\": \"sessions\", \"ui_name\": \"Sessions\", \"type\": \"TYPE_INTEGER\", \"custom_definition\": false}]}",
|
|
609
|
+
"see_also": [
|
|
610
|
+
"action:ga4/run_report",
|
|
611
|
+
"action:ga4/list_properties",
|
|
612
|
+
"action:ga4/list_metrics"
|
|
613
|
+
]
|
|
614
|
+
},
|
|
521
615
|
{
|
|
522
616
|
"id": "action:ga4/get_property_overview",
|
|
523
617
|
"namespace": "ga4",
|
|
524
618
|
"action": "get_property_overview",
|
|
525
619
|
"description": "Aggregate GA4 KPI snapshot for a property over a date range; returns one overview block with users, sessions, page views, key events, and revenue.",
|
|
526
620
|
"long_description": "Primary use:\nHeadline KPIs for a GA4 property over a date range, without dimensional breakdown. Use it for a one-shot snapshot answer.\n\nUse when:\n- The user asks for a property-level summary across a window.\n- You need total/new/active users, sessions, page views, key events, or revenue across the period.\n\nDo not use when:\n- The user needs per-page, per-channel, or per-event breakdown. Use list_top_pages, list_traffic_sources, or list_events.\n- The user needs a daily time series. Use get_daily_trend.\n- The user needs CPA / ROAS or ad spend. Use ads.query_single_dimension.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date_start, date_end.\n\nOutput semantics:\n- overview.total_revenue_micros is in micros (1 USD = 1_000_000); pair with overview.currency for display.\n- overview.bounce_rate is a 0-1 ratio.\n- overview.avg_session_duration_seconds is in seconds.\n- overview.key_events is the GA4 v5+ replacement for the legacy 'conversions' concept.\n- Returns null overview when the property has no synced data for the range.",
|
|
527
|
-
"
|
|
621
|
+
"mode": "read",
|
|
528
622
|
"priority": "primary",
|
|
529
623
|
"requires_review": false,
|
|
530
624
|
"freshness_kind": "synced",
|
|
@@ -563,9 +657,9 @@
|
|
|
563
657
|
"id": "action:ga4/list_events",
|
|
564
658
|
"namespace": "ga4",
|
|
565
659
|
"action": "list_events",
|
|
566
|
-
"description": "Cached GA4 event breakdown for a property over a date range; returns rows of event_name with event_count and
|
|
567
|
-
"long_description": "Primary use:\nEvent-level GA4 analytics
|
|
568
|
-
"
|
|
660
|
+
"description": "Cached GA4 event breakdown for a property over a date range; returns rows of event_name with event_count, event_value_micros, and per-event unique_users (deduplicated users) for funnel / conversion analysis.",
|
|
661
|
+
"long_description": "Primary use:\nEvent-level GA4 analytics \u2014 not limited to conversion events.\n\nUse when:\n- The user asks about any GA4 event volume (scroll, session_start, add_to_cart, purchase, etc.).\n- You need per-event counts and event value sums for a date range.\n\nDo not use when:\n- The user wants only conversion / key-event totals. Use get_conversion_overview.\n- The user wants per-page or per-source breakdown. Use list_top_pages or list_traffic_sources.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date range, and optional event_names filter / limit.\n\nOutput semantics:\n- Default sort is event_count DESC.\n- rows[].event_value_micros sums GA4 event_value in micros; events without value report 0.\n- When event_names is omitted, returns top events ranked by event_count up to limit.\n- Returns [] when the property has no synced event data for the range.",
|
|
662
|
+
"mode": "read",
|
|
569
663
|
"priority": "supporting",
|
|
570
664
|
"requires_review": false,
|
|
571
665
|
"freshness_kind": "synced",
|
|
@@ -608,7 +702,7 @@
|
|
|
608
702
|
"description": "Row cap. Default 100, hard cap 500. page_size accepted as an alias."
|
|
609
703
|
}
|
|
610
704
|
],
|
|
611
|
-
"output_shape": "{\"property\": {\"property_id\": \"123456789\", \"data_freshness\": \"ISO\"}, \"rows\": [{\"event_name\": \"page_view\", \"event_count\": N, \"event_value_micros\": micros}]}",
|
|
705
|
+
"output_shape": "{\"property\": {\"property_id\": \"123456789\", \"data_freshness\": \"ISO\"}, \"rows\": [{\"event_name\": \"page_view\", \"event_count\": N, \"event_value_micros\": micros, \"unique_users\": N|null}], \"unique_users_basis\": \"exact\"|\"approximate\"|null, \"unique_users_note\": \"...\"}",
|
|
612
706
|
"see_also": [
|
|
613
707
|
"action:ga4/list_properties",
|
|
614
708
|
"action:ga4/get_conversion_overview",
|
|
@@ -621,7 +715,7 @@
|
|
|
621
715
|
"action": "list_metrics",
|
|
622
716
|
"description": "Discover GA4 metric slugs, units, and formulas from the Metric Registry before reading them as field names in other ga4.* outputs.",
|
|
623
717
|
"long_description": "Primary use:\nMetric Registry discovery filtered to source=ga4. Same registry as the metrics block in ads.list_dimensions, but scoped to GA4 metrics only.\n\nUse when:\n- You are unsure which metric slug, unit, or formula a GA4 field uses.\n- You need to map a metric slug to its dependency chain or platform support.\n\nDo not use when:\n- You need a queryable dimension list. ga4 has no list_dimensions equivalent; other ga4.* actions return fixed column sets.\n- You need ads-side metric semantics. Use ads.list_dimensions.\n\nWorkflow:\n1. Call this action.\n2. Match returned slugs to columns in get_property_overview, get_daily_trend, list_top_pages, list_traffic_sources, or list_events output.\n\nOutput semantics:\n- rows[].slug is the canonical metric name (e.g. engagement_rate, total_users).\n- rows[].unit is the metric unit class (ratio, micros, seconds, count).\n- rows[].available_on lists the platforms exposing this metric; for source=ga4 it always includes 'ga4'.\n- This is metadata; no property_id or date range needed and no data is queried.",
|
|
624
|
-
"
|
|
718
|
+
"mode": "read",
|
|
625
719
|
"priority": "supporting",
|
|
626
720
|
"requires_review": false,
|
|
627
721
|
"freshness_kind": "synced",
|
|
@@ -638,9 +732,9 @@
|
|
|
638
732
|
"namespace": "ga4",
|
|
639
733
|
"action": "list_properties",
|
|
640
734
|
"description": "Discover org-bound GA4 properties; returns property_id values required by every other ga4.* action.",
|
|
641
|
-
"long_description": "Primary use:\nProperty discovery for the current
|
|
642
|
-
"
|
|
643
|
-
"priority": "
|
|
735
|
+
"long_description": "Primary use:\nProperty discovery for the current brand scope. Use the returned property_id values as the only valid property_id inputs for later ga4.* analytics calls. Only properties granted to the caller's brand are returned.\n\nUse when:\n- The user did not provide a property_id.\n- The user asks which GA4 properties are available.\n- You need to choose a GA4 property before querying overviews, trends, pages, sources, or events.\n\nDo not use when:\n- You already have a property_id from this response in the same workflow.\n- You need ad accounts. Use ads.list_ad_accounts instead.\n\nWorkflow:\n1. Call this action.\n2. Pick one row's property_id.\n3. Reuse that property_id (alias account_id is accepted) in any later ga4.* call.\n\nOutput semantics:\n- rows[].property_id is the external GA4 property id expected by later calls.\n- rows[].data_freshness is the latest completed GA4 sync run finish time; null when never synced.\n\nConstraints:\n- Rows are scoped to the caller's organization and active ResourceBrandGrant.\n- A property absent from this response is not queryable by other ga4 actions.",
|
|
736
|
+
"mode": "read",
|
|
737
|
+
"priority": "supporting",
|
|
644
738
|
"requires_review": false,
|
|
645
739
|
"freshness_kind": "synced",
|
|
646
740
|
"input_params": [
|
|
@@ -664,7 +758,7 @@
|
|
|
664
758
|
"action": "list_top_pages",
|
|
665
759
|
"description": "Cached GA4 top-page ranking for a date range; returns rows of page_path/page_title with views, users, engagement, and key events.",
|
|
666
760
|
"long_description": "Primary use:\nPage-level ranking over a property's synced GA4 data.\n\nUse when:\n- The user asks for most-viewed pages, top landing pages, or best-performing content.\n- You need page_path x per-page metrics for a date range.\n\nDo not use when:\n- The user needs a per-page time series. This action does not split by day.\n- The user needs traffic source breakdown. Use list_traffic_sources.\n- The user needs event-level breakdown. Use list_events.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date range, and optional sort_by / limit.\n\nOutput semantics:\n- Default sort is screen_page_views DESC.\n- rows[].bounce_rate is a 0-1 ratio; rows[].avg_session_duration_seconds is in seconds.\n- rows[].key_events is page-level conversion count (GA4 v5+ naming).\n- Returns [] when the property has no synced page data for the range.",
|
|
667
|
-
"
|
|
761
|
+
"mode": "read",
|
|
668
762
|
"priority": "primary",
|
|
669
763
|
"requires_review": false,
|
|
670
764
|
"freshness_kind": "synced",
|
|
@@ -718,7 +812,7 @@
|
|
|
718
812
|
"action": "list_traffic_sources",
|
|
719
813
|
"description": "Cached GA4 traffic source ranking for a date range; returns rows of session_source/medium/campaign with users, sessions, page views, and revenue.",
|
|
720
814
|
"long_description": "Primary use:\nAcquisition breakdown across session_source x session_medium x session_campaign_name.\n\nUse when:\n- The user asks where traffic comes from, top channels, organic vs paid, or campaign-level acquisition.\n- You need session-level acquisition metrics for a date range.\n\nDo not use when:\n- The user needs page-level data. Use list_top_pages and join client-side.\n- The user needs event-level data. Use list_events.\n- The user needs ad spend, CPA, or ROAS. Use ads.query_single_dimension.\n\nWorkflow:\n1. Call list_properties if property_id is unknown.\n2. Call this action with property_id, date range, and optional sort_by / limit.\n\nOutput semantics:\n- Default sort is sessions DESC.\n- rows[].total_revenue_micros is in micros; rows[].bounce_rate is a 0-1 ratio; rows[].avg_session_duration_seconds is in seconds.\n- rows[].key_events replaces legacy 'conversions' (GA4 v5+).\n- Returns [] when the property has no synced source data for the range.",
|
|
721
|
-
"
|
|
815
|
+
"mode": "read",
|
|
722
816
|
"priority": "primary",
|
|
723
817
|
"requires_review": false,
|
|
724
818
|
"freshness_kind": "synced",
|
|
@@ -765,6 +859,173 @@
|
|
|
765
859
|
"action:ga4/get_daily_trend",
|
|
766
860
|
"action:ga4/get_conversion_overview"
|
|
767
861
|
]
|
|
862
|
+
},
|
|
863
|
+
{
|
|
864
|
+
"id": "action:ga4/run_report",
|
|
865
|
+
"namespace": "ga4",
|
|
866
|
+
"action": "run_report",
|
|
867
|
+
"description": "Live GA4 Data API RunReport fallback for ad-hoc dimension x metric queries that are not covered by cached ga4.* actions.",
|
|
868
|
+
"long_description": "Primary use:\nExecute a constrained GA4 RunReport request against one brand-granted property. Prefer cached actions for standard summaries; use this when the user asks for a GA4 breakdown, filter, or custom field outside the fixed cached shapes.\n\nUse when:\n- The requested dimensions or metrics are not available in cached actions.\n- You need custom GA4 fields discovered through ga4.get_metadata.\n- You need live GA4 results instead of the latest synced parquet snapshot.\n\nDo not use when:\n- A cached action can answer the question; cached actions are cheaper and more stable.\n- You need Google Ads spend, campaign, or keyword data. Use ads.* actions.\n\nSupported DSL:\n- property_id plus either date_ranges[] or date_start/date_end.\n- dimensions[] and metrics[]. metrics is required; dimensions may be empty.\n- dimension_filter and metric_filter support string_filter, in_list_filter, numeric_filter, between_filter, plus and_group/or_group/not_expression.\n- order_bys[] entries must reference requested dimensions or metrics.\n- limit defaults to 100 and is capped at 1000; offset defaults to 0.\n\nOutput semantics:\n- rows are row-shaped dictionaries; columns is the same data pivoted by field.\n- row_count is the GA4 total available rows, not only the returned page length.\n- truncated=true means more rows exist after offset + returned rows.",
|
|
869
|
+
"mode": "read",
|
|
870
|
+
"priority": "advanced",
|
|
871
|
+
"requires_review": false,
|
|
872
|
+
"freshness_kind": "realtime",
|
|
873
|
+
"input_params": [
|
|
874
|
+
{
|
|
875
|
+
"name": "property_id",
|
|
876
|
+
"type": "string",
|
|
877
|
+
"required": true,
|
|
878
|
+
"description": "Property id from list_properties.rows[].property_id. account_id is accepted as an alias.",
|
|
879
|
+
"example": "123456789"
|
|
880
|
+
},
|
|
881
|
+
{
|
|
882
|
+
"name": "date_start",
|
|
883
|
+
"type": "string",
|
|
884
|
+
"required": false,
|
|
885
|
+
"description": "Inclusive start date in YYYY-MM-DD format when date_ranges is omitted.",
|
|
886
|
+
"example": "2026-05-01"
|
|
887
|
+
},
|
|
888
|
+
{
|
|
889
|
+
"name": "date_end",
|
|
890
|
+
"type": "string",
|
|
891
|
+
"required": false,
|
|
892
|
+
"description": "Inclusive end date in YYYY-MM-DD format when date_ranges is omitted.",
|
|
893
|
+
"example": "2026-05-18"
|
|
894
|
+
},
|
|
895
|
+
{
|
|
896
|
+
"name": "date_ranges",
|
|
897
|
+
"type": "list",
|
|
898
|
+
"required": false,
|
|
899
|
+
"description": "Optional GA4 date ranges, each with start_date/end_date. Overrides date_start/date_end.",
|
|
900
|
+
"example": [
|
|
901
|
+
{
|
|
902
|
+
"start_date": "2026-05-01",
|
|
903
|
+
"end_date": "2026-05-18"
|
|
904
|
+
}
|
|
905
|
+
]
|
|
906
|
+
},
|
|
907
|
+
{
|
|
908
|
+
"name": "dimensions",
|
|
909
|
+
"type": "list",
|
|
910
|
+
"required": false,
|
|
911
|
+
"description": "GA4 dimension api_name values from get_metadata.",
|
|
912
|
+
"example": [
|
|
913
|
+
"date",
|
|
914
|
+
"sessionSource"
|
|
915
|
+
]
|
|
916
|
+
},
|
|
917
|
+
{
|
|
918
|
+
"name": "metrics",
|
|
919
|
+
"type": "list",
|
|
920
|
+
"required": true,
|
|
921
|
+
"description": "GA4 metric api_name values from get_metadata.",
|
|
922
|
+
"example": [
|
|
923
|
+
"sessions",
|
|
924
|
+
"totalUsers"
|
|
925
|
+
]
|
|
926
|
+
},
|
|
927
|
+
{
|
|
928
|
+
"name": "limit",
|
|
929
|
+
"type": "integer",
|
|
930
|
+
"required": false,
|
|
931
|
+
"description": "Row cap. Default 100, hard cap 1000."
|
|
932
|
+
},
|
|
933
|
+
{
|
|
934
|
+
"name": "offset",
|
|
935
|
+
"type": "integer",
|
|
936
|
+
"required": false,
|
|
937
|
+
"description": "Zero-based row offset. Default 0."
|
|
938
|
+
}
|
|
939
|
+
],
|
|
940
|
+
"output_shape": "{\"property\": {\"property_id\": \"123456789\", \"data_freshness\": \"ISO\"}, \"dimensions\": [\"date\"], \"metrics\": [\"sessions\"], \"rows\": [{\"date\": \"20260501\", \"sessions\": 42}], \"columns\": {\"date\": [\"20260501\"], \"sessions\": [42]}, \"row_count\": 1, \"truncated\": false, \"limit\": 100, \"offset\": 0}",
|
|
941
|
+
"see_also": [
|
|
942
|
+
"action:ga4/get_metadata",
|
|
943
|
+
"action:ga4/list_properties",
|
|
944
|
+
"action:ga4/get_property_overview"
|
|
945
|
+
]
|
|
946
|
+
},
|
|
947
|
+
{
|
|
948
|
+
"id": "action:posthog/list_projects",
|
|
949
|
+
"namespace": "posthog",
|
|
950
|
+
"action": "list_projects",
|
|
951
|
+
"description": "List the PostHog projects this brand can query.",
|
|
952
|
+
"long_description": "Returns the PostHog projects granted to the current brand (project_id + name). START HERE for any PostHog task: every other posthog action requires one of these project_ids. Do NOT ask the user for a project id \u2014 this action is the source of truth. (Upstream PostHog project listing is org-wide and not available.)",
|
|
953
|
+
"mode": "read",
|
|
954
|
+
"priority": "normal",
|
|
955
|
+
"requires_review": false,
|
|
956
|
+
"freshness_kind": "realtime",
|
|
957
|
+
"input_params": [],
|
|
958
|
+
"output_shape": "data.rows[].{project_id, name}",
|
|
959
|
+
"see_also": []
|
|
960
|
+
},
|
|
961
|
+
{
|
|
962
|
+
"id": "action:posthog/list_tools",
|
|
963
|
+
"namespace": "posthog",
|
|
964
|
+
"action": "list_tools",
|
|
965
|
+
"description": "List the PostHog analytics tools available for a project.",
|
|
966
|
+
"long_description": "Returns the live PostHog MCP tool catalog for one granted project, each annotated with `requires_review`. The default response is a slim catalog without input schemas. Pass `tool` to fetch one exact tool's full input schema before calling `posthog/query`. Tools with `requires_review=true` (writes, or anything not on our read-only allowlist) must go through `posthog/request_change`, not `posthog/query`.",
|
|
967
|
+
"mode": "read",
|
|
968
|
+
"priority": "normal",
|
|
969
|
+
"requires_review": false,
|
|
970
|
+
"freshness_kind": "realtime",
|
|
971
|
+
"input_params": [
|
|
972
|
+
{
|
|
973
|
+
"name": "project_id",
|
|
974
|
+
"type": "string",
|
|
975
|
+
"required": false,
|
|
976
|
+
"description": "PostHog project id (from posthog/list_projects).",
|
|
977
|
+
"example": "12345"
|
|
978
|
+
},
|
|
979
|
+
{
|
|
980
|
+
"name": "tool",
|
|
981
|
+
"type": "string",
|
|
982
|
+
"required": false,
|
|
983
|
+
"description": "Exact PostHog tool name; when provided, returns that tool's full input schema.",
|
|
984
|
+
"example": "insight-query"
|
|
985
|
+
}
|
|
986
|
+
],
|
|
987
|
+
"output_shape": "data.project_id, data.tools[].{name, description, requires_review[, input_schema when tool is provided]}",
|
|
988
|
+
"see_also": []
|
|
989
|
+
},
|
|
990
|
+
{
|
|
991
|
+
"id": "action:posthog/query",
|
|
992
|
+
"namespace": "posthog",
|
|
993
|
+
"action": "query",
|
|
994
|
+
"description": "Run a read-only PostHog analytics tool (trends, funnels, HogQL, etc.).",
|
|
995
|
+
"long_description": "Forwards a read-only PostHog tool call for one granted project. Common tools: `insight-query` (trends / funnels / retention), `execute-sql` (HogQL \u2014 read-only, validated), `read-data-schema` (use before writing HogQL to get real field names). Get the project_id from `posthog/list_projects` (never ask the user for it). Only allowlisted read tools are accepted here; a write or unvetted tool returns `requires_review` \u2014 call `posthog/request_change` for those. The response echoes which project was queried.",
|
|
996
|
+
"mode": "read",
|
|
997
|
+
"priority": "normal",
|
|
998
|
+
"requires_review": false,
|
|
999
|
+
"freshness_kind": "realtime",
|
|
1000
|
+
"input_params": [
|
|
1001
|
+
{
|
|
1002
|
+
"name": "project_id",
|
|
1003
|
+
"type": "string",
|
|
1004
|
+
"required": true,
|
|
1005
|
+
"description": "PostHog project id (from posthog/list_projects).",
|
|
1006
|
+
"example": "12345"
|
|
1007
|
+
},
|
|
1008
|
+
{
|
|
1009
|
+
"name": "tool",
|
|
1010
|
+
"type": "string",
|
|
1011
|
+
"required": true,
|
|
1012
|
+
"description": "Exact PostHog tool name from posthog/list_tools.",
|
|
1013
|
+
"example": "insight-query"
|
|
1014
|
+
},
|
|
1015
|
+
{
|
|
1016
|
+
"name": "arguments",
|
|
1017
|
+
"type": "object",
|
|
1018
|
+
"required": false,
|
|
1019
|
+
"description": "Tool arguments object per the tool's input schema.",
|
|
1020
|
+
"example": {
|
|
1021
|
+
"query": {
|
|
1022
|
+
"kind": "TrendsQuery"
|
|
1023
|
+
}
|
|
1024
|
+
}
|
|
1025
|
+
}
|
|
1026
|
+
],
|
|
1027
|
+
"output_shape": "data.{project_id, tool, is_error, content[], structured, truncated}",
|
|
1028
|
+
"see_also": []
|
|
768
1029
|
}
|
|
769
1030
|
]
|
|
770
1031
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA;gFACgF;AAMhF,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA;gFACgF;AAMhF,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CA0FjG"}
|