GTM Tools

Give the agent the whole GTM data surface — LinkedIn, Reddit, verified emails, buying signals, geocoding — behind one bearer token. This skill covers setup and the call contract. The three workflow skills in the same bundle (outbound-sales, linkedin-copywriter, reddit-community-manager) build on top of it.

The one thing that trips everyone up

Two hosts, and they are not interchangeable:

If a call returns 405, fix the host before debugging anything else.

Setup

1. Get an API key

Three paths, pick by context.

A human is present — send a verification code, then redeem it:

curl -s -X POST "https://api.gtm-tools.sh/api/v0/get_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@yourcompany.com"}'

curl -s -X POST "https://api.gtm-tools.sh/api/v0/get_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@yourcompany.com","code":"123456"}'
# → { "api_key": "sk_..." }

No human is present — register autonomously via the auth.md protocol. One call, no signup form, own isolated workspace, 100 free tokens:

curl -s -X POST "https://api.gtm-tools.sh/agent/identity" \
  -H "Content-Type: application/json" \
  -d '{"type":"anonymous"}'
# → { "access_token":"sk_...", "token_type":"bearer", "expires_in":31536000, ... }

To bind the key to a known user's workspace instead, send {"type":"identity_assertion","assertion_type":"verified_email","assertion":"user@example.com"}, then submit the emailed code to /agent/identity/claim and poll /oauth/token with grant_type=urn:workos:agent-auth:grant-type:claim.

The CLI is installed — browser sign-in, key stored in ~/.gtm-tools/config.json:

gtm-tools admin login

Revoke any key with curl -X POST https://api.gtm-tools.sh/oauth/revoke -d 'token=sk_...', or revoke_api_key / gtm-tools admin keys revoke <id>. Note that admin login revokes the workspace's previous CLI (…)-named keys, so don't hard-code one into CI.

2. Export it

export GTM_TOOLS_API_KEY="sk_..."

3. Connect sessions (only for session-backed tools)

LinkedIn and Reddit writes, plus a few reads, run through a real logged-in browser session pooled by the extension. Check before assuming:

curl -s -X POST "https://api.gtm-tools.sh/api/v0/list_connected_linkedin_accounts" \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" -H "Content-Type: application/json" -d '{}' | jq .

Empty list means the user must install the extension and press Connect:

curl -fsSL https://api.gtm-tools.sh/extension/install.sh | bash

Each ready row carries a linkedin_username / reddit_username — pass it as senderUsername to write tools. Both tools cost 0, so checking is always free.

How to call any tool

Every tool is the same shape. Tool name in the path, JSON body, bearer header:

curl -s -X POST "https://api.gtm-tools.sh/api/v0/TOOL_NAME" \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...arguments...}' | jq .

The same tools are also exposed over MCP at https://api.gtm-tools.sh/mcp (Streamable HTTP) and through the gtm-tools CLI. Full catalog with token costs and arguments: references/tools.md. Never hardcode costs — get_token_balance returns the live table.

Metering: what actually costs tokens

$1 = 100 tokens. New workspaces start with 100 free. The cost is debited before the tool runs, and there is no automatic refund, which is the only rule you need to predict a bill:

So: check list_connected_*_accounts and get_token_balance (both free) before fanning out, filter cheaply before hydrating expensively, and honor retry_after_seconds instead of retrying tightly.

Top up with buy_tokens ({"amount_usd":25}) or enable set_auto_reload once and stop thinking about it.

Error contract

Branch on the HTTP status, never on message text:

A 200 carrying status: "not_found" is a real answer: the tool did the work and there is nothing to return. Do not retry it.

Cost-aware sequencing

The expensive tools are expensive for a reason (they fan out upstream). Order the work so they run on the smallest possible set:

• detect_signal (0 + 5 per firing detector) qualifies accounts before any LinkedIn spend.
• get_linkedin_company_url (2) then list_linkedin_company_employees (30) — always pass title_filters, since the cost is identical whether you return everyone or the four people you want.
• search_linkedin_company_employees (5) is the cheap SERP-only alternative when name + headline + URL is enough.
• get_email (5) runs per candidate, so filter the employee list first.
• list_linkedin_company_employees_posts (80) is the most expensive tool in the catalog. Use it deliberately.
• Cache what doesn't move: company IDs, profile URLs, and verified emails are stable for weeks.

Related skills

Once setup works, hand the actual workflow to the specialist skill in this bundle:

Docs for agents: https://gtm-tools.sh/llms.txt is the page index, and appending .md to any docs URL returns clean markdown.