Skip to main content
Glama

Connect popularity source

connect_popularity

Connect Apple Ads, Google Ads Keyword Planner, or an imported CSV/JSON file as a real keyword popularity source; credentials are stored securely for later popularity fetches.

Instructions

Connect a source of REAL keyword popularity: apple_ads (Apple Ads API: clientId, teamId, keyId, private key, optional orgId), google_ads_planner (Google Ads Keyword Planner through the owner's own Google Cloud project at Basic access: customerId, refreshToken, oauthClientId, oauthClientSecret, optional loginCustomerId; the owner can also sign in from Settings › Popularity instead) or imported (a popularity export file at filePath). Prefer file paths for keys. Secrets go to the OS keychain and are never returned. Then call fetch_popularity.

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": {
      "source": "<source>"
    },
    "name": "connect_popularity"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyIdNoapple_ads: key id.
orgIdNoapple_ads: org id when several are visible.
storeNoStore: "apple" (App Store) or "google" (Google Play).
sourceYesPopularity source.
teamIdNoapple_ads: team id.
clientIdNoapple_ads: client id.
filePathNoimported: path to the export file (CSV / JSON).
customerIdNogoogle_ads_planner: customer id.
refreshTokenNogoogle_ads_planner: OAuth refresh token.
oauthClientIdNogoogle_ads_planner: OAuth client id.
privateKeyPemNoapple_ads: PEM contents (prefer privateKeyPath).
developerTokenNogoogle_ads_planner: legacy developer token (optional; Google retired them, access comes from the Cloud project).
privateKeyPathNoapple_ads: path to the private key PEM.
loginCustomerIdNogoogle_ads_planner: manager account id.
oauthClientSecretNogoogle_ads_planner: OAuth client secret.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.2.7
    • changedInput schema / properties / developerToken / description
      Previous value: -"google_ads_planner: developer token."New value: +"google_ads_planner: legacy developer token (optional; Google retired them, access comes from the Cloud project)."
  2. First observedv0.1.7

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: secrets are stored in the OS keychain and never returned, and file paths are preferred over inline keys. It does not say whether reconnecting replaces or merges an existing configuration, which matters given idempotentHint=false.

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?

Front-loaded with the purpose, then the source list, then the security note and next step. The parenthetical credential lists are dense but each item earns its place; only minor tightening is possible.

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?

For a 15-parameter, no-output-schema connection tool, the description covers source selection, credential grouping, secret handling, and the required follow-up call. It omits failure behavior and whether an existing connection is overwritten, which are the remaining gaps.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by grouping parameters under each source and flagging the preference for privateKeyPath over privateKeyPem. That routing information is not derivable from the flat schema alone.

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

Purpose5/5

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

States a specific verb and resource ('Connect a source of REAL keyword popularity') and enumerates the three supported sources with their credential sets, so the agent knows exactly what the tool does. It also explicitly hands off to the sibling fetch_popularity, distinguishing the connect step from the fetch step.

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

Usage Guidelines5/5

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

Gives per-source conditions (apple_ads, google_ads_planner, imported) and names an alternative path for Google ('the owner can also sign in from Settings › Popularity instead'). It also states the required follow-up action ('Then call fetch_popularity'), leaving little to inference.

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