Common issues

The first three problems account for almost every support message about the MCP server. The rest are the ones that come up next. Each has a short fix.

Connection issues

Symptoms: Sync GTM tools don’t appear in your client, the server shows as disconnected / needs login, tool calls hang or fail with 401 Unauthorized.

MCP sessions expire. When they do, the client usually keeps showing the server as configured — it just stops working. Refreshing the connection fixes most of these.

Full per-client steps live in the setup guides.

No result returned

Symptoms: The tool call succeeds but comes back empty, or your AI reports “no data found” for a person or company you know exists.

This is nearly always the input, not the data. Two things to check, in order.

1. Check the required parameters

Every tool page lists its required input in the spec box at the top, and every accepted parameter below it. Open the page for the tool that came back empty:

• Browse all 50 tools →

Most common mismatches:

• Wrong identifier type. find_work_email takes a LinkedIn profile URL, not a name. enrich_organization takes a domain, not a company name.
• Company name instead of domain. Domains are exact matches; names are fuzzy and often miss. Pass stripe.com, not “Stripe”.
• Wrong enum string. Filters like seniority_levels accept fixed values — c_suite, vp, director, senior. “C-level” and “Vice President” match nothing.
• No filter at all. Search tools like find_people have no strictly required field, but a call with nothing to match on returns noise or nothing.

2. Follow the best prompting practices

Each tool page has a Best prompting practices section listing the failure modes specific to that tool. Read it, then rewrite your prompt to match and run it again.

More credits charged than expected

Symptoms: A single request consumed far more credits than the tool’s listed cost.

The tool cost isn’t the issue — the number of calls is. Given a broad instruction, your AI will happily loop a tool across every row it can find. A 1-credit tool run on 200 contacts is 200 credits.

Narrow the prompt

Say exactly how much work you want done:

• Bad: “Find emails for everyone at these companies.”
• Good: “Find work emails for the first 10 contacts in this list only. Stop after 10.”

Specifics that keep spend predictable:

• Name the exact count — “the first 10”, not “the top ones”.
• Set limit deliberately on search tools. For find_people, limit is the cost dial — every profile returned bills 0.3 credits.
• Cap the paging. “Stop after 3 pages” prevents a broad search from walking the whole result set.
• Search first, enrich second. Filter down to the profiles you want before spending credits on emails or phone numbers.
• Avoid expensive tools in loops. find_mobile_number and find_work_phone are 12 credits per call — run those on a shortlist, never a full list.

Give strict rules to follow

Put hard limits in the prompt and require the AI to stop rather than improvise:

Rules:
- Use only find_work_email. Do not call any other tool.
- Process exactly the 10 rows I pasted. Do not expand the list.
- One call per row. Do not retry failures.
- Run check_credits before you start and after you finish, and report both.
- If anything is ambiguous, stop and ask me instead of guessing.

Only some tools show up

Symptoms: The server connects, but your client lists 20 of the 50 tools — and the one you need is missing.

Most MCP clients cap how many tools they expose to the model at once. When you run several MCP servers side by side, the combined list gets truncated, and Sync GTM tools can be the ones cut.

• Disable MCP servers you’re not using for this session. The fewer servers connected, the more Sync GTM tools survive the cap.
• Check for a tool filter in your client’s MCP settings — Claude App, Claude Code, and Cursor all let you enable or disable tools per server. A tool switched off there won’t be called no matter how you phrase the prompt.
• Reconnect after upgrading. Clients cache the tool list from the last successful handshake. If the catalogue changed, refresh the connection to pull the current one.
• Confirm the tool exists. The tools catalogue is the source of truth for what’s live — 50 tools, each with its own page.

The AI answered without calling a tool

Symptoms: You asked for a work email or company profile and got a confident answer instantly — but your credit balance didn’t move, and the data is wrong.

Models will answer from training data if the prompt doesn’t clearly demand a lookup. Nothing is charged, because nothing was looked up.

How to force a real call:

• Name the tool. “Use find_work_email to get the email for this LinkedIn URL” beats “what’s their email?”.
• Ask for the evidence. “Show me the raw tool output” makes a fabricated answer obvious.
• Bracket with check_credits. Run check_credits before and after — a spend of zero means no tool ran.
• Verify anything critical. Pass an email through verify_email (0.3 credits) before it enters a sequence.

The AI picked the wrong tool

Symptoms: You get a result, but it’s the wrong shape — a broad multi-company search when you wanted one company, or a company profile when you wanted a tech stack. Credits are spent either way.

Several tools answer near-identical questions, and models pick by name similarity. The usual mix-ups:

Fix it by naming the tool in the prompt — "Use `find_people_within_company` on stripe.com" — and adding “do not call any other tool”. Each tool page has a Related tools table showing when to reach for the neighbour instead.

The tool needs an identifier you don’t have

Symptoms: The tool errors or returns nothing on most rows, and your list has emails or company names but no LinkedIn URLs.

Contact tools like find_work_email, find_mobile_number, and linkedin_profile_posts key off a LinkedIn profile URL. Company tools key off a domain or a LinkedIn company URL — job_openings_growth_rate and head_count_growth_rate require the LinkedIn page URL specifically.

Chain a lookup first rather than dropping the rows:

• Email → LinkedIn: find_linkedin_from_work_email (2 credits), then run the tool you wanted.
• Company name → domain: resolve it with find_companies, then pass the domain.

With a mixed list, segment first — run the LinkedIn-based tools on rows that already have a URL, reverse-lookup the rest, then re-run. Tell your AI to report rows it skipped instead of silently dropping them.

Timeouts and rate limits on large batches

Symptoms: A run over a few hundred rows works for a while, then rows start failing with timeouts or rate-limit errors.

The limits come from the upstream data providers, not your client. They’re transient — the same call usually succeeds on a retry.

• Batch it. Roughly 20 concurrent calls is a safe ceiling. Fire 20, write the results back, then start the next 20.
• Retry the failures, not the batch. Up to 4 attempts, about 10 seconds apart. Rows that already succeeded shouldn’t be re-run — that’s a second charge for the same data.
• Don’t retry an empty result. A null result means “not found”, not “failed”. Retrying it burns credits and returns the same nothing.
• Don’t retry auth or credit errors. Those are systemic — fix the connection or the balance instead.
• Write results as you go, so a run that dies halfway leaves you with the completed rows.

The sync-mcp agent  has this batching and retry behaviour built in — worth installing before any bulk run.

Out of credits

Symptoms: Tool calls stop working mid-run, or fail immediately with an insufficient-credit error.

Credit-based actions pause once the balance hits zero. Nothing is queued or partially charged.

• Run check_credits (free) to see the balance.
• Top up or change plan on the billing page.
• Credits are tied to your account, not one workspace — a balance drop can come from another workspace or a teammate’s run.
• Credits reset monthly and don’t roll over, so a balance that looks lower than yesterday may just be a new billing period. See Credits & API usage.
• Connect your own API keys to skip Sync GTM credits on supported integrations entirely.

Before a bulk run, do the arithmetic: rows × cost per call. 200 rows through a 12-credit phone tool is 2,400 credits.

Results look outdated or incomplete

Symptoms: A job title is one role behind, headcount doesn’t match LinkedIn, or a record comes back with half the fields filled.

Sync GTM reads from third-party providers, and each refreshes on its own schedule. A person who moved last week may not have propagated yet.

• Partial records are normal. Waterfall enrichment stops at the first provider that returns a hit — that provider may not carry every field.
• Try a different identifier. A LinkedIn URL and a work email can resolve through different providers and return different coverage for the same person.
• Confirm a job change with check_job_change rather than assuming the title on file is current.
• Verify before you send. verify_email checks deliverability now, regardless of when the address was sourced.
• Re-enrich on a schedule for accounts that matter, instead of trusting a list built months ago.

Still stuck?

• Check the Troubleshooting notes on the MCP overview for sign-in specifics.
• Join the Sync GTM Slack Community .
• Contact support through the chat widget on docs.syncgtm.com .

Next steps

• Set up your client — 9 step-by-step guides
• Browse every tool with parameters and credit costs
• What you can do with the MCP server

Keep learning

Two courses take these tools past the reference page — clustered by GTM job, then chained into workflows.