mcp-x-brand-presence-mapper

Map X Twitter Brand Presence

map_x_brand_presence

Read-onlyIdempotent

Resolve a company domain to its official X handle, profile URL, and follower metrics. Returns one flat row; optionally use your own X API token for full counts at any batch size.

Instructions

Resolve a company domain to that company's official X (Twitter) handle and profile URL, with follower count, bio and account age where X serves them. Returns one flat Clay ready row. Runs keyless out of the box and X rate limits that route aggressively, so on a large batch some rows return the handle and URL with the counts marked not_extractable; supplying your own X API bearer token removes that limit and returns full metrics at any batch size. A guessed handle that fails the identity check is reported as identity_mismatch rather than returned as the company's, and a company with no X account reports x_status not_found. Read x_status before any count. Read only; requires an APIFY_TOKEN and consumes Apify credits per call.

Input Schema

Name	Required	Description
`handle`	No	Optional. The X handle with or without the leading @, for example Shopify. Supplying it skips discovery and goes straight to the fetch.
`skipCache`	No	When "false" (default) a successful lookup is cached for seven days and reused. Set "true" to force a fresh fetch. Sent as a string for Clay compatibility.
`company_name`	No	Optional. Improves search accuracy and is what the identity gate checks a discovered profile against, so supplying it reduces wrong matches.
`company_domain`	No	Bare company domain, for example shopify.com. Supply this or a handle. With a domain the actor runs full discovery; with a handle it skips straight to the fetch.
`xApiBearerToken`	No	YOUR OWN X API v2 bearer token, free to create at developer.x.com. OPTIONAL: leave it empty and the actor still resolves handles, profile URLs and follower counts, but X rate limits the public route so on a large batch some rows return not_extractable instead of counts. Supplying a token removes that limit and every row returns full metrics. Your token is used for your run only, is never stored, and is never shared with another run.
`includeFollowerCounts`	No	When "true" (default) the profile page is fetched and the counts are extracted. Set "false" to resolve the profile URL only, which is cheaper and needs no proxy. Sent as a string for Clay compatibility.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.1.1Oct 15, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedv1.0.0Sep 8, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations by disclosing keyless operation, aggressive X rate limiting on large batches, the not_extractable degradation, identity_mismatch on failed identity checks, x_status not_found for absent accounts, the APIFY_TOKEN requirement, and per-call credit consumption.

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?

Purpose and return shape are front-loaded, and every sentence carries operational information. It is somewhat dense and repeats the token/rate-limit story already present in the xApiBearerToken schema description, which is the only real waste.

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

Completeness5/5

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

With no output schema and all six parameters optional, the description supplies the missing pieces: return shape, failure statuses, auth/credit requirements, and caching behavior. An agent has everything needed to call it and interpret results.

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 meaning the schema doesn't: the handle path skips discovery, company_name drives the identity gate that produces identity_mismatch, and the token removes the rate limit. These tie parameters to observable outcomes rather than restating field docs.

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?

Opens with a specific verb+resource+output: 'Resolve a company domain to that company's official X (Twitter) handle and profile URL, with follower count, bio and account age'. It also states the return shape ('one flat Clay ready row'), so the agent knows exactly what the tool produces.

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

Usage Guidelines4/5

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

Gives conditional guidance: supplying a handle skips discovery, a domain runs full discovery, and 'Read x_status before any count' tells the agent how to consume results. No siblings exist to differentiate against, and it doesn't explicitly say when not to use the tool, so it falls short of a 5.

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

map_x_brand_presenceA