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

ghl-mcp-server-v2

by zackscriven

ghl_ad_google_audience_list

Read-onlyIdempotent

Retrieve Google Ads combined audiences for a location; use limit and pageToken to paginate through results and fetch every audience batch.

Instructions

Get audiences Retrieve Google Ads combined audiences for a location. Without limit the response is a plain array. When limit is provided (max 100, default 100) the response is a paginated { audiences, paging } envelope; pass pageToken (from paging.next) to fetch the next batch. Endpoint: GET /ad-publishing/google/audiences (Version header: v3; source: v3/ad-publishing-v3.json) OAuth scopes: adPublishing.readonly Pagination params: limit — pass them to page through full result sets.

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>"
    },
    "name": "ghl_ad_google_audience_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoPage size for a paginated fetch (max 100, defaults to 100). When set, the response is a { audiences, paging } envelope instead of a plain array.
pageTokenNoOpaque cursor for the next batch, taken from the previous response paging.next
locationIdYesLocation identifier

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.1.0
    • removedInput schema / properties / isDraft
      Removed value: -{
      -  "description": "Is draft",
      -  "example": true,
      -  "type": "boolean"
      -}
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Page size for a paginated fetch (max 100, defaults to 100). When set, the response is a { audiences, paging } envelope instead of a plain array.",
      +  "example": "100",
      +  "type": "string"
      +}
    • changedInput schema / properties / locationId / example
      Previous value: -"HChooFuiyPpVYzeJ4HMe"New value: +"loc_abc123"
    • addedInput schema / properties / pageToken
      Added value: +{
      +  "description": "Opaque cursor for the next batch, taken from the previous response paging.next",
      +  "example": "100",
      +  "type": "string"
      +}
  2. First observedv2.0.0

TDQS

A3.9/5.0
Behavior5/5

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

Beyond the annotations (which already declare read-only, idempotent, non-destructive), it adds the key behavioral quirk: the response shape is a plain array without limit and a { audiences, paging } envelope with it. It also names the required OAuth scope (adPublishing.readonly) and where pageToken comes from.

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?

The response-shape and pagination explanation is front-loaded and earns its place. The trailing line 'Pagination params: limit — pass them to page through full result sets' is redundant and misattributes paging to limit rather than pageToken, adding noise.

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

Completeness4/5

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

With no output schema, the description usefully explains both possible return shapes and how to advance pages. It omits error behavior and what audience fields are returned, but those are secondary for a read-only list call.

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%, so all three parameters already carry descriptions that say the same things (limit's max/default and envelope switch, pageToken from paging.next, locationId). The description re-states these but adds no syntax or edge-case detail beyond the schema.

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?

It names a specific verb and resource: retrieve Google Ads combined audiences for a location. The name and description together let an agent tell it apart from audience_get and audience_upsert, but the description never explicitly contrasts them.

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

Usage Guidelines3/5

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

It implies usage: list audiences for a location, optionally paginated. But it does not say when to choose this tool over ghl_ad_google_audience_get, or what prerequisites exist (an existing Google Ads integration/account) beyond the OAuth reference.

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