Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_ad_google_segment_upsert

Idempotent

Create or update a Google Ads audience segment in GoHighLevel, defining keywords, URLs, apps, or rule-based members to target ad campaigns. Upsert avoids duplicate segments.

Instructions

Upsert segment Create or update a Google Ads audience segment Endpoint: PUT /ad-publishing/google/segments (Version header: v3; source: v3/ad-publishing-v3.json) OAuth scopes: adPublishing.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "locationId": "<locationId>",
      "type": "<type>",
      "body": "<body>"
    },
    "name": "ghl_ad_google_segment_upsert"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
typeYesSegment type
locationIdYesLocation identifier

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv2.1.0
    • addedInput schema / properties / body / properties / members / items / title
      Added value: +"MemberDTO"
    • changedInput schema / properties / body / properties / ruleBasedUserList / allOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "flexibleRuleUserList": {
      -        "allOf": [
      -          {
      -            "properties": {
      -              "exclusiveOperands": {
      -                "description": "Exclusive rule operands",
      -                "example": [],
      -                "items": {
      -                  "properties": {
      -                    "lookbackWindowDays": {
      -                      "description": "Lookback window in days",
      -                      "example": 30,
      -                      "type": "number"
      -                    },
      -                    "rule": {
      -                      "allOf": [
      -                        {
      -                          "properties": {
      -                            "ruleItemGroups": {
      -                              "description": "List of rule item groups",
      -                              "example": [
      -                                {
      -                                  "ruleItems": [
      -                                    {
      -                                      "name": "url__",
      -                                      "stringRuleItem": {
      -                                        "operator": "CONTAINS",
      -                                        "value": "/products"
      -                                      }
      -                                    }
      -                                  ]
      -                                }
      -                              ],
      -                              "items": {
      -                                "properties": {
      -                                  "ruleItems": {
      -                                    "description": "List of rule items",
      -                                    "example": [
      -                                      {
      -                                        "name": "url__",
      -                                        "stringRuleItem": {
      -                                          "operator": "CONTAINS",
      -                                          "value": "/products"
      -                                        }
      -                                      }
      -                                    ],
      -                                    "items": {
      -                                      "properties": {
      -                                        "name": {
      -                                          "description": "Rule item name",
      -                                          "enum": [
      -                                            "url__",
      -                                            "referrer__"
      -                                          ],
      -                                          "example": "url__",
      -                                          "type": "string"
      -                                        },
      -                                        "stringRuleItem": {
      -                                          "allOf": [
      -                                            {
      -                                              "properties": {
      -                                                "operator": {
      -                                                  "description": "Rule operator",
      -                                                  "example": "CONTAINS",
      -                                                  "type": "string"
      -                                                },
      -                                                "value": {
      -                                                  "description": "Rule value",
      -                                                  "example": "/products",
      -                                                  "type": "string"
      -                                                }
      -                                              },
      -                                              "required": [
      -                                                "operator",
      -                                                "value"
      -                                              ],
      -                                              "type": "object"
      -                                            }
      -                                          ],
      -                                          "description": "String rule item condition",
      -                                          "example": {
      -                                            "operator": "CONTAINS",
      -                                            "value": "/products"
      -                                          }
      -                                        }
      -                                      },
      -                                      "required": [
      -                                        "name",
      -                                        "stringRuleItem"
      -                                      ],
      -                                      "type": "object"
      -                                    },
      -                                    "type": "array"
      -                                  }
      -                                },
      -                                "required": [
      -                                  "ruleItems"
      -                                ],
      -                                "type": "object"
      -                              },
      -                              "type": "array"
      -                            }
      -                          },
      -                          "required": [
      -                            "ruleItemGroups"
      -                          ],
      -                          "type": "object"
      -                        }
      -                      ],
      -                      "description": "Rule definition",
      -                      "example": {
      -                        "ruleItemGroups": [
      -                          {
      -                            "ruleItems": [
      -                              {
      -                                "name": "url__",
      -                                "stringRuleItem": {
      -                                  "operator": "CONTAINS",
      -                                  "value": "/products"
      -                                }
      -                              }
      -                            ]
      -                          }
      -                        ]
      -                      }
      -                    }
      -                  },
      -                  "required": [
      -                    "lookbackWindowDays",
      -                    "rule"
      -                  ],
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              "inclusiveOperands": {
      -                "description": "Inclusive rule operands",
      -                "example": [
      -                  {
      -                    "lookbackWindowDays": 30,
      -                    "rule": {
      -                      "ruleItemGroups": []
      -                    }
      -                  }
      -                ],
      -                "items": {
      -                  "properties": {
      -                    "lookbackWindowDays": {
      -                      "description": "Lookback window in days",
      -                      "example": 30,
      -                      "type": "number"
      -                    },
      -                    "rule": {
      -                      "allOf": [
      -                        {
      -                          "properties": {
      -                            "ruleItemGroups": {
      -                              "description": "List of rule item groups",
      -                              "example": [
      -                                {
      -                                  "ruleItems": [
      -                                    {
      -                                      "name": "url__",
      -                                      "stringRuleItem": {
      -                                        "operator": "CONTAINS",
      -                                        "value": "/products"
      -                                      }
      -                                    }
      -                                  ]
      -                                }
      -                              ],
      -                              "items": {
      -                                "properties": {
      -                                  "ruleItems": {
      -                                    "description": "List of rule items",
      -                                    "example": [
      -                                      {
      -                                        "name": "url__",
      -                                        "stringRuleItem": {
      -                                          "operator": "CONTAINS",
      -                                          "value": "/products"
      -                                        }
      -                                      }
      -                                    ],
      -                                    "items": {
      -                                      "properties": {
      -                                        "name": {
      -                                          "description": "Rule item name",
      -                                          "enum": [
      -                                            "url__",
      -                                            "referrer__"
      -                                          ],
      -                                          "example": "url__",
      -                                          "type": "string"
      -                                        },
      -                                        "stringRuleItem": {
      -                                          "allOf": [
      -                                            {
      -                                              "properties": {
      -                                                "operator": {
      -                                                  "description": "Rule operator",
      -                                                  "example": "CONTAINS",
      -                                                  "type": "string"
      -                                                },
      -                                                "value": {
      -                                                  "description": "Rule value",
      -                                                  "example": "/products",
      -                                                  "type": "string"
      -                                                }
      -                                              },
      -                                              "required": [
      -                                                "operator",
      -                                                "value"
      -                                              ],
      -                                              "type": "object"
      -                                            }
      -                                          ],
      -                                          "description": "String rule item condition",
      -                                          "example": {
      -                                            "operator": "CONTAINS",
      -                                            "value": "/products"
      -                                          }
      -                                        }
      -                                      },
      -                                      "required": [
      -                                        "name",
      -                                        "stringRuleItem"
      -                                      ],
      -                                      "type": "object"
      -                                    },
      -                                    "type": "array"
      -                                  }
      -                                },
      -                                "required": [
      -                                  "ruleItems"
      -                                ],
      -                                "type": "object"
      -                              },
      -                              "type": "array"
      -                            }
      -                          },
      -                          "required": [
      -                            "ruleItemGroups"
      -                          ],
      -                          "type": "object"
      -                        }
      -                      ],
      -                      "description": "Rule definition",
      -                      "example": {
      -                        "ruleItemGroups": [
      -                          {
      -                            "ruleItems": [
      -                              {
      -                                "name": "url__",
      -                                "stringRuleItem": {
      -                                  "operator": "CONTAINS",
      -                                  "value": "/products"
      -                                }
      -                              }
      -                            ]
      -                          }
      -                        ]
      -                      }
      -                    }
      -                  },
      -                  "required": [
      -                    "lookbackWindowDays",
      -                    "rule"
      -                  ],
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              "inclusiveRuleOperator": {
      -                "description": "Operator for combining inclusive operands",
      -                "example": "AND",
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "inclusiveOperands",
      -              "exclusiveOperands"
      -            ],
      -            "type": "object"
      -          }
      -        ],
      -        "description": "Flexible rule user list configuration",
      -        "example": {
      -          "exclusiveOperands": [],
      -          "inclusiveOperands": [],
      -          "inclusiveRuleOperator": "AND"
      -        }
      -      },
      -      "prepopulationStatus": {
      -        "description": "Prepopulation status",
      -        "enum": [
      -          "REQUESTED"
      -        ],
      -        "example": "REQUESTED",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "flexibleRuleUserList"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "flexibleRuleUserList": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "exclusiveOperands": {
      +                "description": "Exclusive rule operands",
      +                "example": [
      +                  {
      +                    "lookbackWindowDays": 30,
      +                    "rule": {
      +                      "ruleItemGroups": [
      +                        {
      +                          "ruleItems": [
      +                            {
      +                              "name": "url__",
      +                              "stringRuleItem": {
      +                                "operator": "CONTAINS",
      +                                "value": "/products"
      +                              }
      +                            }
      +                          ]
      +                        }
      +                      ]
      +                    }
      +                  }
      +                ],
      +                "items": {
      +                  "properties": {
      +                    "lookbackWindowDays": {
      +                      "description": "Lookback window in days",
      +                      "example": 30,
      +                      "type": "number"
      +                    },
      +                    "rule": {
      +                      "allOf": [
      +                        {
      +                          "properties": {
      +                            "ruleItemGroups": {
      +                              "description": "List of rule item groups",
      +                              "example": [
      +                                {
      +                                  "ruleItems": [
      +                                    {
      +                                      "name": "url__",
      +                                      "stringRuleItem": {
      +                                        "operator": "CONTAINS",
      +                                        "value": "/products"
      +                                      }
      +                                    }
      +                                  ]
      +                                }
      +                              ],
      +                              "items": {
      +                                "properties": {
      +                                  "ruleItems": {
      +                                    "description": "List of rule items",
      +                                    "example": [
      +                                      {
      +                                        "name": "url__",
      +                                        "stringRuleItem": {
      +                                          "operator": "CONTAINS",
      +                                          "value": "/products"
      +                                        }
      +                                      }
      +                                    ],
      +                                    "items": {
      +                                      "properties": {
      +                                        "name": {
      +                                          "description": "Rule item name",
      +                                          "enum": [
      +                                            "url__",
      +                                            "referrer__"
      +                                          ],
      +                                          "example": "url__",
      +                                          "type": "string"
      +                                        },
      +                                        "stringRuleItem": {
      +                                          "allOf": [
      +                                            {
      +                                              "properties": {
      +                                                "operator": {
      +                                                  "description": "Rule operator",
      +                                                  "example": "CONTAINS",
      +                                                  "type": "string"
      +                                                },
      +                                                "value": {
      +                                                  "description": "Rule value",
      +                                                  "example": "/products",
      +                                                  "type": "string"
      +                                                }
      +                                              },
      +                                              "required": [
      +                                                "operator",
      +                                                "value"
      +                                              ],
      +                                              "title": "StringRuleItemDTO",
      +                                              "type": "object"
      +                                            }
      +                                          ],
      +                                          "description": "String rule item condition",
      +                                          "example": {
      +                                            "operator": "CONTAINS",
      +                                            "value": "/products"
      +                                          }
      +                                        }
      +                                      },
      +                                      "required": [
      +                                        "name",
      +                                        "stringRuleItem"
      +                                      ],
      +                                      "title": "RuleItemDTO",
      +                                      "type": "object"
      +                                    },
      +                                    "type": "array"
      +                                  }
      +                                },
      +                                "required": [
      +                                  "ruleItems"
      +                                ],
      +                                "title": "RuleItemGroupDTO",
      +                                "type": "object"
      +                              },
      +                              "type": "array"
      +                            }
      +                          },
      +                          "required": [
      +                            "ruleItemGroups"
      +                          ],
      +                          "title": "RuleDTO",
      +                          "type": "object"
      +                        }
      +                      ],
      +                      "description": "Rule definition",
      +                      "example": {
      +                        "ruleItemGroups": [
      +                          {
      +                            "ruleItems": [
      +                              {
      +                                "name": "url__",
      +                                "stringRuleItem": {
      +                                  "operator": "CONTAINS",
      +                                  "value": "/products"
      +                                }
      +                              }
      +                            ]
      +                          }
      +                        ]
      +                      }
      +                    }
      +                  },
      +                  "required": [
      +                    "lookbackWindowDays",
      +                    "rule"
      +                  ],
      +                  "title": "RuleOperandDTO",
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              "inclusiveOperands": {
      +                "description": "Inclusive rule operands",
      +                "example": [
      +                  {
      +                    "lookbackWindowDays": 30,
      +                    "rule": {
      +                      "ruleItemGroups": [
      +                        {
      +                          "ruleItems": [
      +                            {
      +                              "name": "url__",
      +                              "stringRuleItem": {
      +                                "operator": "CONTAINS",
      +                                "value": "/products"
      +                              }
      +                            }
      +                          ]
      +                        }
      +                      ]
      +                    }
      +                  }
      +                ],
      +                "items": {
      +                  "properties": {
      +                    "lookbackWindowDays": {
      +                      "description": "Lookback window in days",
      +                      "example": 30,
      +                      "type": "number"
      +                    },
      +                    "rule": {
      +                      "allOf": [
      +                        {
      +                          "properties": {
      +                            "ruleItemGroups": {
      +                              "description": "List of rule item groups",
      +                              "example": [
      +                                {
      +                                  "ruleItems": [
      +                                    {
      +                                      "name": "url__",
      +                                      "stringRuleItem": {
      +                                        "operator": "CONTAINS",
      +                                        "value": "/products"
      +                                      }
      +                                    }
      +                                  ]
      +                                }
      +                              ],
      +                              "items": {
      +                                "properties": {
      +                                  "ruleItems": {
      +                                    "description": "List of rule items",
      +                                    "example": [
      +                                      {
      +                                        "name": "url__",
      +                                        "stringRuleItem": {
      +                                          "operator": "CONTAINS",
      +                                          "value": "/products"
      +                                        }
      +                                      }
      +                                    ],
      +                                    "items": {
      +                                      "properties": {
      +                                        "name": {
      +                                          "description": "Rule item name",
      +                                          "enum": [
      +                                            "url__",
      +                                            "referrer__"
      +                                          ],
      +                                          "example": "url__",
      +                                          "type": "string"
      +                                        },
      +                                        "stringRuleItem": {
      +                                          "allOf": [
      +                                            {
      +                                              "properties": {
      +                                                "operator": {
      +                                                  "description": "Rule operator",
      +                                                  "example": "CONTAINS",
      +                                                  "type": "string"
      +                                                },
      +                                                "value": {
      +                                                  "description": "Rule value",
      +                                                  "example": "/products",
      +                                                  "type": "string"
      +                                                }
      +                                              },
      +                                              "required": [
      +                                                "operator",
      +                                                "value"
      +                                              ],
      +                                              "title": "StringRuleItemDTO",
      +                                              "type": "object"
      +                                            }
      +                                          ],
      +                                          "description": "String rule item condition",
      +                                          "example": {
      +                                            "operator": "CONTAINS",
      +                                            "value": "/products"
      +                                          }
      +                                        }
      +                                      },
      +                                      "required": [
      +                                        "name",
      +                                        "stringRuleItem"
      +                                      ],
      +                                      "title": "RuleItemDTO",
      +                                      "type": "object"
      +                                    },
      +                                    "type": "array"
      +                                  }
      +                                },
      +                                "required": [
      +                                  "ruleItems"
      +                                ],
      +                                "title": "RuleItemGroupDTO",
      +                                "type": "object"
      +                              },
      +                              "type": "array"
      +                            }
      +                          },
      +                          "required": [
      +                            "ruleItemGroups"
      +                          ],
      +                          "title": "RuleDTO",
      +                          "type": "object"
      +                        }
      +                      ],
      +                      "description": "Rule definition",
      +                      "example": {
      +                        "ruleItemGroups": [
      +                          {
      +                            "ruleItems": [
      +                              {
      +                                "name": "url__",
      +                                "stringRuleItem": {
      +                                  "operator": "CONTAINS",
      +                                  "value": "/products"
      +                                }
      +                              }
      +                            ]
      +                          }
      +                        ]
      +                      }
      +                    }
      +                  },
      +                  "required": [
      +                    "lookbackWindowDays",
      +                    "rule"
      +                  ],
      +                  "title": "RuleOperandDTO",
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              "inclusiveRuleOperator": {
      +                "description": "Operator for combining inclusive operands",
      +                "example": "AND",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "inclusiveOperands",
      +              "exclusiveOperands"
      +            ],
      +            "title": "FlexibleRuleUserListDTO",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "Flexible rule user list configuration",
      +        "example": {
      +          "exclusiveOperands": [
      +            {
      +              "lookbackWindowDays": 30,
      +              "rule": {
      +                "ruleItemGroups": [
      +                  {
      +                    "ruleItems": [
      +                      {
      +                        "name": "url__",
      +                        "stringRuleItem": {
      +                          "operator": "CONTAINS",
      +                          "value": "/products"
      +                        }
      +                      }
      +                    ]
      +                  }
      +                ]
      +              }
      +            }
      +          ],
      +          "inclusiveOperands": [
      +            {
      +              "lookbackWindowDays": 30,
      +              "rule": {
      +                "ruleItemGroups": [
      +                  {
      +                    "ruleItems": [
      +                      {
      +                        "name": "url__",
      +                        "stringRuleItem": {
      +                          "operator": "CONTAINS",
      +                          "value": "/products"
      +                        }
      +                      }
      +                    ]
      +                  }
      +                ]
      +              }
      +            }
      +          ],
      +          "inclusiveRuleOperator": "AND"
      +        }
      +      },
      +      "prepopulationStatus": {
      +        "description": "Prepopulation status",
      +        "enum": [
      +          "REQUESTED"
      +        ],
      +        "example": "REQUESTED",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "flexibleRuleUserList"
      +    ],
      +    "title": "RuleBasedUserListDTO",
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / body / properties / ruleBasedUserList / example / flexibleRuleUserList / exclusiveOperands
      Previous value: -[]New value: +[
      +  {
      +    "lookbackWindowDays": 30,
      +    "rule": {
      +      "ruleItemGroups": [
      +        {
      +          "ruleItems": [
      +            {
      +              "name": "url__",
      +              "stringRuleItem": {
      +                "operator": "CONTAINS",
      +                "value": "/products"
      +              }
      +            }
      +          ]
      +        }
      +      ]
      +    }
      +  }
      +]
    • changedInput schema / properties / body / properties / ruleBasedUserList / example / flexibleRuleUserList / inclusiveOperands
      Previous value: -[]New value: +[
      +  {
      +    "lookbackWindowDays": 30,
      +    "rule": {
      +      "ruleItemGroups": [
      +        {
      +          "ruleItems": [
      +            {
      +              "name": "url__",
      +              "stringRuleItem": {
      +                "operator": "CONTAINS",
      +                "value": "/products"
      +              }
      +            }
      +          ]
      +        }
      +      ]
      +    }
      +  }
      +]
    • changedInput schema / properties / body / properties / type / description
      Previous value: -"Segment type"New value: +"Google custom-audience type, used only when the `type` query parameter is `CUSTOM_SEGMENTS`. Defaults to `AUTO` when omitted. This is NOT the same field as the `type` query parameter, which selects which kind of segment to upsert — settable values here are `AUTO`, `INTEREST`, `PURCHASE_INTENT` and `SEARCH`."
    • changedInput schema / properties / body / properties / type / example
      Previous value: -"CUSTOM_SEGMENTS"New value: +"AUTO"
    • addedInput schema / properties / body / title
      Added value: +"UpsertSegmentDTO"
  2. First observedv2.0.0

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuine context — the PUT endpoint and the required OAuth scope adPublishing.write — but stays silent on upsert semantics (whether supplying an `id` in the body switches to update) and on what happens to unspecified fields.

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

Conciseness4/5

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

Four short lines, front-loaded with the purpose, then endpoint and scope metadata — no padding. The endpoint/source string is somewhat operational rather than agent-facing, but it is compact enough to earn its space.

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

Completeness3/5

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

For a mutation tool with a deeply nested body and no output schema, the description omits the create-vs-update discriminator and response shape, relying entirely on the schema. Adequate but leaves real gaps for a 3-required-param write operation.

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

Parameters3/5

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

Schema coverage is 100%, with rich nested descriptions including the important note that body.type differs from the type query parameter. The description adds no parameter-level meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (upsert = create or update) and resource (Google Ads audience segment), making the operation unambiguous. It does not, however, distinguish itself from the closely named sibling ghl_ad_google_audience_upsert, which an agent could easily confuse with this segment tool.

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

Usage Guidelines2/5

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

There is no guidance on when to choose this over ghl_ad_google_audience_upsert, ghl_ad_google_segment_get/list/delete, or ghl_ad_google_segment_offline_job_create. The only hint is the word 'upsert', which implies create-or-update but says nothing about prerequisites or exclusions.

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

Deploy Server

Other Tools