The Influship MCP server provides AI-native tools for influencer marketing, enabling creator discovery, profile lookup, content analysis, and campaign fit assessment.
Preview without an account: Fetch a sample creator preview to see what Influship returns before connecting an account.
Search & Discover Creators: Find creators by name, handle, niche, topic, audience, location, or engagement metrics using standard or semantic search.
Autocomplete Creator Names: Resolve partial handles or names to canonical creator IDs.
Find Lookalike Creators: Surface creators similar to one or more seed creators, with optional follower/engagement filters.
Score Creators Against a Campaign Brief: Evaluate how well specific creators fit a campaign brief, returning match scores and structured reasons.
Fetch Creator Profiles: Retrieve full records or detailed social profiles (bio, followers, engagement, growth) for individual creators or batch-fetch up to 100 profiles at once.
Analyze Creator Posts: Access a creator's posts sorted by recency or engagement metrics (likes, views, comments), with pagination.
Fetch Raw Instagram Post Data: Retrieve fresh Instagram post metadata (coauthors, tagged users, paid partnerships, music, location, etc.) individually or in batches of up to 20.
Transcribe Instagram Video Posts: Transcribe Instagram video posts by shortcode, individually or in batches of up to 10, with optional language detection.
Enables creator discovery, profile lookup, post retrieval, and Instagram post transcript analysis for influencer marketing workflows.
Provides creator search and profile resolution across TikTok for influencer marketing and prospecting.
Supports creator profile lookup and post data retrieval from YouTube for influencer marketing campaigns.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Influship MCP find beauty creators with 100k+ followers on Instagram"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI-native creator discovery for influencer marketing workflows. Influship gives ChatGPT, Claude, Cursor, Codex, VS Code, and other MCP-compatible agents typed tools for creator search, lookalikes, profile lookup, post lookup, and Instagram post transcript analysis.
Search for creators by audience, niche, location, platform, and campaign-fit criteria.
Find creator lookalikes from known winners or competitor talent lists.
Resolve creator profiles and social handles across Instagram, TikTok, and YouTube-oriented workflows.
Pull creator records, posts, and Instagram transcript data into briefs, prospecting lists, market maps, and outreach research.
Related MCP server: Instagram Complete MCP Server
Use the hosted Streamable HTTP server when your MCP client supports remote MCP:
claude mcp add influship --transport http https://mcp.influship.com/mcp --header "X-API-Key: YOUR_KEY"Use the npm package for clients that only support stdio:
INFLUSHIP_API_KEY=YOUR_KEY npx -y @influship/mcpThe package is a small stdio bridge to the hosted Influship MCP server. It keeps the data, auth, billing, and rate limits on the same production API surface as the remote server.
For local development or staging:
INFLUSHIP_API_KEY=YOUR_KEY INFLUSHIP_MCP_URL=http://localhost:8080/mcp npx -y @influship/mcp{
"mcpServers": {
"influship": {
"command": "npx",
"args": ["-y", "@influship/mcp"],
"env": {
"INFLUSHIP_API_KEY": "YOUR_KEY"
}
}
}
}search_creators
autocomplete_creators
find_lookalike_creators
match_creators
get_creator
get_profile
lookup_profiles
get_posts
Instagram post and transcript tools when enabled on the hosted MCP server
API keys: https://developers.influship.com
Hosted MCP endpoint: https://mcp.influship.com/mcp
The official MCP Registry metadata lives in server.json and advertises both
the hosted Streamable HTTP server and the npm stdio package.
pnpm install
pnpm test
pnpm build
npm publish --access publicAfter npm publish, submit server.json with the official MCP Registry publisher
and use this repository URL for directory submissions.
Autocomplete creator names, usernames, or display names from partial input.
Use this for fast lookup when the user types a partial handle or name and you need to
resolve it to canonical creator IDs (e.g., "find @cris" or "who's that fitness coach
called Jane?"). Cheap and fast — prefer over search_creators for handle-style
queries where the user already knows roughly who they want.
Use get_profile instead when the user gives an exact platform+username pair. Use
search_creators for the same fuzzy creator lookup behavior with a less typeahead-
specific name. Use semantic_search_creators only for discovery by topic, niche,
audience, geography, or content style, not for resolving a known creator.
Examples:
User: "Who is that fitness coach called Jane?" -> use this tool.
User: "Find @cris..." -> use this tool to resolve the partial handle.
User: "Pull @niickjackson on Instagram" -> use get_profile, not this tool.
Returns a short list of matching creators with their IDs, platforms, and display names.
Use the IDs returned here as input to get_creator, find_lookalike_creators, or
match_creators for downstream operations.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query (min 2 characters) | |
| limit | No | Maximum results to return | |
| scope | No | Which platforms to include in results | all_platforms |
| platform | No | Filter by platform |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: 'Cheap and fast', 'Returns a short list of matching creators with their IDs, platforms, and display names', and shows how results feed into downstream tools. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but well-structured: purpose, usage guidance, examples, and downstream usage. Every section serves a distinct function and there's no fluff. Slightly verbose but highly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, alternatives, examples, return format, and downstream integration. Given the tool's simplicity and the presence of an output schema, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the meaning of q by referencing 'partial input' but doesn't add details about limit, scope, or platform beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Autocomplete creator names, usernames, or display names from partial input.' It explicitly differentiates from siblings by stating 'prefer over search_creators', 'Use get_profile instead', and 'Use semantic_search_creators only for discovery...'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use: 'Use this for fast lookup when the user types a partial handle or name' and 'Cheap and fast — prefer over search_creators'. Also explicit exclusions: 'Use get_profile instead when the user gives an exact platform+username pair' and 'Use semantic_search_creators only for discovery...'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find creators SIMILAR to one or more seed creators.
Use this when the user already knows a creator they like and wants more like them (e.g., "find creators like @therock", "find more creators like these three I just booked"). Seeds are blended via creator-profile + visual-style + fact embeddings to surface similar accounts.
Seeds are passed in seed_creator_ids (canonical UUIDs) and/or seed_profiles
(platform + username; resolve handles via autocomplete_creators first if needed).
Returns a ranked list of similar creators with scores. limit caps results
(default 25, max 100). Use the flat follower, engagement-rate, and verified fields
to constrain results.
Use semantic_search_creators instead when you have a topic/niche but no seed.
Use match_creators when you have specific candidates and want to score their fit
against a brief.
Examples:
User: "Find creators like @niickjackson on Instagram" -> use this tool with
seed_profiles: [{ platform: "instagram", username: "niickjackson" }].
User: "Find news creators with 1M+ followers" -> use semantic_search_creators,
not this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return. | |
| cursor | No | Pagination cursor from a previous response. | |
| verified | No | When set, only return verified or unverified creators. | |
| max_followers | No | Maximum follower count. | |
| min_followers | No | Minimum follower count. | |
| seed_profiles | No | Seed creators identified by platform and username. | |
| seed_creator_ids | No | Seed creators identified by canonical Influship creator UUID. | |
| max_engagement_rate | No | Maximum engagement rate as a percentage from 0 to 100. | |
| min_engagement_rate | No | Minimum engagement rate as a percentage from 0 to 100. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show `readOnlyHint: true` and `destructiveHint: false`, so the description doesn't need to reiterate safety. It adds value by explaining the blending mechanism (creator-profile + visual-style + fact embeddings) and the returning of a ranked list with scores. However, it could briefly mention pagination or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening sentence, a usage section, parameter details, and examples. Every sentence adds value, and there is no redundancy or fluff. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, an output schema, and a need to distinguish from 13 siblings, the description covers all key aspects: purpose, usage context, seeds, filtering, examples, and limits. It is complete and leaves no major gaps for an AI agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context by explaining the role of `seed_profiles` and `seed_creator_ids`, mentioning the default and max for `limit`, and noting that filter fields (follower count, engagement rate, verified) can constrain results. This helps the agent understand which parameters are central.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding creators similar to seed creators. It uses specific verbs like 'Find creators SIMILAR' and distinguishes from siblings by name-dropping alternative tools. Examples reinforce the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool (user has seed creators) versus alternatives (`semantic_search_creators` for topics, `match_creators` for specific candidates). Also includes concrete examples of when to use and when not to, making it easy for the agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full record for a single creator by ID or exact platform username.
Use this when you already have either:
a canonical creator UUID returned by search_creators,
semantic_search_creators, autocomplete_creators, or
find_lookalike_creators; or
an exact platform+username pair such as platform "instagram" and username "niickjackson".
Pass include: ['profiles'] to also receive the creator's social profile
summaries when using a creator UUID. For platform+username inputs, this tool resolves
through the profile endpoint and returns the profile record plus the underlying creator
record, so you already get the matched profile context.
Examples:
User: "Get creator 123e4567-e89b-12d3-a456-426614174000" -> call with id.
User: "Get @niickjackson on Instagram" -> call with platform "instagram" and
username "niickjackson", or use get_profile if profile metrics are the main need.
User: "Tell me about @niickjackson and include his profiles" -> use platform
"instagram" and username "niickjackson"; then use get_profile/get_posts for
platform-specific metrics and content if needed.
Use lookup_profiles for batch exact profile lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Creator unique identifier | |
| include | No | Additional data to include in response | |
| platform | No | Social platform for the username. | |
| username | No | Platform username or handle without the @ sign. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds context about resolution behavior for platform+username inputs and the effect of the include parameter. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and examples. Slightly long but every sentence adds value; examples are instructive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema and annotations, the description is comprehensive: covers purpose, usage, parameters, examples, and tool differentiation. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds value by explaining the two usage modes, providing examples, and clarifying the include parameter's behavior in both modes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Fetch the full record for a single creator by ID or exact platform username.' Distinguishes two input modes and contrasts with sibling tools like search_creators and get_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('when you already have a canonical creator UUID or exact platform+username pair') and when to use alternatives (get_profile for profile metrics, lookup_profiles for batch lookups).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch raw Instagram post-page data by shortcode.
Use this when the user needs fresh raw Instagram post metadata that is not guaranteed on regular cached post-list endpoints yet, including coauthors, tagged users, paid partnership metadata, product mentions, music attribution, location, display resources, and video versions.
| Name | Required | Description | Default |
|---|---|---|---|
| shortcode | Yes | Instagram post shortcode from a /p/, /reel/, or /tv/ URL |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations by specifying that the data is raw and fresh, and enumerating the exact content types (coauthors, tagged users, paid partnership metadata, etc.), which helps the agent set expectations about data completeness and structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action and resource, and the second sentence provides usage guidance and data scope. Every sentence earns its place with no filler, making it an exemplary concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter), the presence of an output schema, and safe annotations, the description fully covers the necessary context: what data is returned, when to use the tool, and why it exists. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of the single parameter 'shortcode' with a clear description ('Instagram post shortcode from a /p/, /reel/, or /tv/ URL'). The tool description does not add additional parameter semantics, but the schema fully documents the parameter, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('raw Instagram post-page data by shortcode'), clearly distinguishing it from sibling tools like get_instagram_posts (plural) and get_instagram_post_transcript. It further differentiates by enumerating the unique data fields it returns (coauthors, paid partnership metadata, video versions, etc.), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-to-use scenario: 'when the user needs fresh raw Instagram post metadata that is not guaranteed on regular cached post-list endpoints yet.' This implies an alternative (cached post-list endpoints) and a condition for exclusion, though it does not name a sibling tool explicitly. The guidance is clear and contextually useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch raw Instagram post-page data for a bounded list of shortcodes through the raw API.
Returns one item per requested shortcode with per-item success or error details.
| Name | Required | Description | Default |
|---|---|---|---|
| shortcodes | Yes | Instagram post shortcodes from /p/, /reel/, or /tv/ URLs |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns per-item success/error details and uses 'raw API', providing useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with the action. No wasted words, efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter fully documented, annotations covering safety, and an output schema, the description adds return structure details. Missing edge cases but adequate for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the parameter. The description adds minimal extra meaning ('bounded list') but is not needed; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (fetch), resource (Instagram post-page data), and scope (bounded list of shortcodes). It distinguishes from siblings like get_instagram_post (singular) and get_instagram_post_transcripts (transcripts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. While 'bounded list' implies batch usage, it doesn't contrast with singular get_instagram_post or other siblings. Missing alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe an Instagram video post by shortcode through the raw API.
For now this retranscribes every request. Cached transcript reads are planned as a follow-up, and public pricing is intended to stay the same for live and cached transcript delivery.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Optional transcript language code. Omit to auto-detect. | |
| shortcode | Yes | Instagram post shortcode from a /p/, /reel/, or /tv/ URL |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral context: 'retranscribes every request' (no caching) and future caching plans. However, it does not disclose rate limits, authentication, or error handling for invalid shortcodes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states purpose concisely, second adds a caveat about retranscription and future plans. Every sentence earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and good annotations, the description explains current behavior (no caching, language auto-detection). It lacks details on error cases (e.g., invalid shortcode) but is largely complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptions for both parameters (shortcode and language). The description does not add further meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Transcribe an Instagram video post by shortcode', specifying a clear verb and resource. It distinguishes from siblings like get_instagram_post (retrieve post metadata) and get_instagram_post_transcripts (plural, likely batch).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that 'for now this retranscribes every request' and mentions future caching, but does not explicitly guide when to use this tool versus alternatives like get_instagram_post_transcripts or how to obtain shortcodes. Usage context is implied but not definitive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe a bounded list of Instagram video posts by shortcode through the raw API.
For now this retranscribes every request. Successful items include the raw post data used for transcription.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Optional transcript language code. Omit to auto-detect. | |
| shortcodes | Yes | Instagram video post shortcodes from /p/, /reel/, or /tv/ URLs |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: 'retranscribes every request' (no caching) and 'includes raw post data'. Annotations already indicate read-only, but description enriches with specific behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste. Front-loaded with action and resource, second sentence adds essential caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description adequately covers behavior (retranscribes, includes raw data) and boundaries (bounded list). No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds limited value for parameters. 'Bounded list' reinforces maxItems, but no new detail about language or shortcodes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it transcribes Instagram video posts by shortcode, and mentions 'bounded list' distinguishing from singular sibling 'get_instagram_post_transcript'. Differentiates from other sibling tools that retrieve posts without transcripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for batch transcription (bounded list, max 10), and mentions retranscribing every request, but does not explicitly compare to alternatives or state when to use singular vs batch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a creator's posts, sorted and paginated.
Use this when the user asks to see what a creator has posted (e.g., "show me Jane's
last 20 posts", "what are this creator's top-engagement reels?", "pull recent posts
from creator-id ABC"). Identify the creator by either creator_id (UUID) OR
(platform + username).
sort defaults to "recent" (newest first); use "top_engagement" for the highest-
engagement posts, or one of "most_likes" / "most_views" / "most_comments" for a
specific metric. limit defaults to 12 and is capped at 50. Pass cursor from a
previous response's next_cursor to paginate.
Returns post records (caption, media URL, like/comment/view counts, timestamps),
plus has_more and next_cursor for pagination.
Examples:
User: "Show @niickjackson's recent Instagram posts" -> use this tool with platform "instagram" and username "niickjackson".
User: "Is @niickjackson a fit for Pixel?" -> use this after get_profile when
the fit analysis needs recent content evidence, then call match_creators.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order | recent |
| limit | No | Maximum posts to return | |
| cursor | No | Pagination cursor for next page | |
| platform | No | Platform (required with username) | |
| username | No | Username (required with platform) | |
| creator_id | No | Creator ID (use this OR platform+username) |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds valuable behavioral details: defaults for sort and limit, cap at 50, pagination via cursor, and the return fields (caption, media URL, counts, timestamps plus has_more/next_cursor). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: starts with a one-sentence summary, then details usage, parameter behavior, return data, and ends with two concrete examples. Each sentence adds value, and it is not overly long. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, sorting, pagination, output schema), the description covers all essential aspects: how to identify the creator, sorting options, pagination mechanics, return fields, and even example usage scenarios. The presence of an output schema reduces the need to detail return values, but the description still mentions key fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the mutual exclusivity of creator_id vs platform+username, states defaults and max for limit, describes the sort options with brief explanations, and clarifies the cursor’s source. This enhances the agent's understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch a creator's posts, sorted and paginated' and provides concrete examples of user queries that trigger this tool. It distinguishes from sibling tools by clarifying the scope (a specific creator, with sorting/pagination) and mentions an alternative path (using after get_profile), making the purpose clear and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit when-to-use scenarios like 'when the user asks to see what a creator has posted' and gives example queries. It explains the two identification methods (creator_id or platform+username) and mentions a workflow after get_profile. While it does not explicitly list when not to use, the examples and context provide strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single social profile by (platform, username).
Always use this first when the user gives an exact handle on a specific platform
(for example "@niickjackson on Instagram") and you need the full profile: bio,
follower/engagement metrics, recent activity, growth, and the canonical creator ID.
Pass exactly the username they typed without the @ sign — case-insensitive matching is
handled server-side. Do not use search_creators for an exact platform+username
lookup.
Examples:
User: "Pull @niickjackson on Instagram" -> use this tool with platform "instagram" and username "niickjackson".
User: "Tell me about instagram.com/niickjackson" -> parse the platform and username, then use this tool.
User: "Is @niickjackson a fit for Pixel?" -> use this tool first, then call
get_posts and/or match_creators if the task needs content or fit analysis.
Returns the profile record plus the underlying creator record. If you already have a
creator UUID, use get_creator instead. For batch lookups by handle, use
lookup_profiles.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | Yes | Social platform for the username. | |
| username | Yes | Platform username or handle without the @ sign. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context beyond that: it specifies the return structure (profile + creator record) and notes case-insensitive matching. This adds value but does not disclose major new behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, starting with a clear purpose, then usage guidelines, examples, return info, and alternative tools. Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, output schema exists, annotations present), the description covers all needed aspects: purpose, when to use, parameter handling, return content, and sibling differentiation. It leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds extra guidance: 'Pass exactly the username they typed without the @ sign' and 'case-insensitive matching is handled server-side', plus examples of parsing platform and username. This meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single social profile by (platform, username)' and details the returned fields (bio, metrics, activity, growth, creator ID). It distinguishes from siblings like search_creators, get_creator, and lookup_profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Always use this first when the user gives an exact handle on a specific platform' and provides examples. It also tells when not to use it: 'Do not use search_creators for an exact platform+username lookup' and suggests alternatives like get_creator or lookup_profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a ChatGPT user wants to see what Influship can return before linking an account.
Fetches one configured sample creator with social profile context. This is a low-cost preview tool and should not be used for search, discovery, matching, or lookalike requests. After showing the preview, tell the user that real live creator data, search, lookalikes, matching, posts, and transcripts require connecting an Influship account. Explain that they can authorize either an Influship SaaS subscription, where usage counts against monthly bundled credits, or an Influship API account, where usage is billed pay-as-you-go under API billing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it is a low-cost preview tool and includes detailed behavioral instructions for the agent (the script to tell user about account linking). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with key purpose and usage. Each of the 5 sentences adds value: use case, action, exclusions, post-action script. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple no-param tool with output schema, description provides complete context: purpose, usage boundaries, behavioral traits, and agent instructions. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters. Baseline 4 as per guidelines. Description does not need to add parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches one configured sample creator for preview. Distinguishes from sibling tools by explicitly stating it should not be used for search, discovery, matching, or lookalike requests. Specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (preview before linking account) and when not to use (not for search, etc.). Also provides post-action instructions for the agent on what to tell the user, which further guides appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch-fetch up to 100 profiles by (platform, username) pairs.
Use this when the user has a list of handles and you need profile data for all of
them at once (e.g., "give me follower counts for these 30 accounts I'm considering"
or "which of @a @b @c are real accounts?"). One round-trip beats 30 calls to
get_profile.
Use this for exact batch handle lookup, not semantic discovery. For one exact
platform+username pair, use get_profile. For partial or fuzzy handle/name input,
use search_creators or autocomplete_creators. Use
semantic_search_creators only for topical/niche/audience discovery where
false-positive semantic matches are acceptable.
Examples:
User: "Compare @a, @b, and @c on Instagram" -> use this tool for the exact handle batch.
User: "Give me follower counts for these 30 accounts" -> use this tool.
User: "Find wellness creators in Austin" -> use semantic_search_creators, not
this tool.
The response splits results into data (profiles found) and not_found (the
(platform, username) pairs that weren't recognized). Profiles are returned in no
particular order — re-correlate via the platform/username fields if you need to
preserve input order.
| Name | Required | Description | Default |
|---|---|---|---|
| profiles | Yes | Profiles to lookup |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses important runtime behavior: the response splits into `data` and `not_found`, and profiles are returned in no particular order, requiring re-correlation via platform/username. It also notes the round-trip efficiency benefit. These are not inferable from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a when-to-use paragraph with examples, an explicit alternatives paragraph, and a return-behavior note. Every sentence earns its place, and the most critical information is front-loaded. Despite being a bit long, it is appropriately sized for the tool's complexity and avoids fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete given the tool's complexity. It covers purpose, usage, examples, alternatives, and return behavior. The existence of an output schema means the description need not re-explain return values, but it still adds critical context like unordered results and the not_found split. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the `profiles` array with item definitions, required fields, and min/max constraints (100% coverage). The description adds meaningful context by framing these as '(platform, username) pairs' for 'exact batch handle lookup' and explaining that not_found contains unrecognized pairs. This goes slightly beyond the schema's bare 'Profiles to lookup' with extra usage semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Batch-fetch up to 100 profiles by (platform, username) pairs' – a specific verb, resource, and constraint. It then clearly distinguishes this tool from siblings, noting that `get_profile` handles a single exact pair, `search_creators` and `autocomplete_creators` handle fuzzy input, and `semantic_search_creators` handles topical discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'when the user has a list of handles and you need profile data for all of them at once.' It also provides concrete examples of user requests that should and should not use this tool, and names alternative tools for other scenarios (e.g., semantic_search_creators for 'Find wellness creators in Austin'). No ambiguity remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score how well specific creators fit a campaign brief or search intent.
Use this when the user already has candidate creators in mind and wants to evaluate fit (e.g., "rate these 5 creators for a vegan cookbook launch", "which of these is the best match for my crypto audience?"). For each creator the API returns a match score (0-1), a good/neutral/avoid decision, and structured reasons.
Pass candidates in creator_ids (canonical UUIDs) and/or profiles
(platform + username). intent_query is the brief the LLM reasons against;
intent_context is optional extra context (target audience, brand values,
prior collabs).
Use semantic_search_creators when you don't have candidates yet and need topical
or niche discovery. Use search_creators first when you only need to resolve rough
creator names/handles into candidates.
Use find_lookalike_creators when you want creators similar to known good fits.
Examples:
User: "Is @niickjackson a fit for Pixel?" -> use this tool after resolving the
exact Instagram profile with get_profile; call get_posts first if recent
content context is needed.
User: "Rate these five creators for a vegan cookbook launch" -> use this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| profiles | No | Candidate creators identified by platform and username. | |
| creator_ids | No | Candidate creators identified by canonical Influship creator UUID. | |
| intent_query | Yes | Campaign brief or matching intent. | |
| intent_context | No | Optional extra campaign context, audience, brand values, or prior collabs. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns a match score (0-1), a good/neutral/avoid decision, and structured reasons, and it clarifies that candidates can be passed as UUIDs and/or profiles. This goes beyond annotations, though it doesn't describe sorting, pagination, or failure behavior, so it isn't a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-organized: core purpose first, followed by parameter guidance, sibling disambiguation, and concrete examples. Each sentence adds value, though the example section is somewhat verbose and could be tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, full schema coverage, an output schema, and 13 sibling tools, the description provides sufficient context: it explains what the tool does, when to use it, how to handle different input forms, how it relates to siblings, and includes both brief and full user-intent examples. There are no significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds practical parameter semantics by stating that creator_ids and profiles can be used 'and/or', that intent_query is 'the brief the LLM reasons against', and that intent_context is optional extra context (target audience, brand values, prior collabs). This helps an agent compose valid inputs beyond what the schema alone conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Score how well specific creators fit a campaign brief or search intent.' It clearly distinguishes this from sibling tools by noting the tool evaluates existing candidates, whereas semantic_search_creators is for discovery and search_creators for resolving handles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: use when the user already has candidate creators in mind and wants fit evaluation. It also names alternatives with explicit conditions ('Use semantic_search_creators when you don't have candidates yet', 'Use search_creators first when you only need to resolve rough creator names/handles', 'Use find_lookalike_creators when you want creators similar to known good fits'). Realistic user-phrasing examples reinforce usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a creator by name/handle, while preserving legacy semantic creator search.
Use this as the default creator lookup tool when the user gives a creator-ish string but not a canonical creator UUID: a handle, partial handle, display name, creator name, or profile-ish text. This is cheap, fast, and backed by the creator lookup index.
If the user gives an exact handle on a specific platform (for example "@niickjackson on
Instagram"), prefer get_profile first because it returns the full platform profile.
If you need to resolve a rough creator name or partial handle first, use this tool with
query_type: "creator_lookup".
For backward compatibility, this tool still accepts the old semantic-search fields
(platforms, follower/engagement filters, creator_kinds) and routes legacy calls
to the semantic endpoint unless the query clearly contains a handle/profile URL. For
new topical/niche discovery calls such as "fitness creators in NYC" or "vegan recipe
creators with high engagement", prefer semantic_search_creators because its name is
explicit and less likely to be confused with exact creator lookup.
Examples:
User: "Find @cris" -> use this tool with query "cris" and query_type "creator_lookup".
User: "Who is that fitness coach called Jane?" -> use this tool with query "Jane" and query_type "creator_lookup".
User: "Pull @niickjackson on Instagram" -> use get_profile with platform
"instagram" and username "niickjackson".
User: "Find news creators with 1M+ followers" -> use semantic_search_creators,
not this tool.
Returns either autocomplete-style creator lookup results or legacy semantic results,
depending on routing. Use returned creator IDs with get_creator,
find_lookalike_creators, or match_creators; use returned platform usernames
with get_profile or get_posts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return. | |
| query | Yes | Natural-language semantic discovery query by topic, niche, audience, geography, or content style. Do not pass exact handles or usernames here; use get_profile, lookup_profiles, or autocomplete_creators instead. | |
| scope | No | Which linked platforms to include in each lookup result. | all_platforms |
| platform | No | Optional platform to narrow username matching. | |
| verified | No | When set, only return verified or unverified creators. | |
| platforms | No | Platforms to search. Omit for all. | |
| query_type | No | Use creator_lookup for specific names/handles and semantic_discovery for topical/niche discovery. Auto routes exact handles and profile URLs to lookup, and keeps legacy semantic-search behavior otherwise. | auto |
| creator_kinds | No | Optional creator kind filter. Omit for no creator-kind filter. | |
| max_followers | No | Maximum follower count. | |
| min_followers | No | Minimum follower count. | |
| max_engagement_rate | No | Maximum engagement rate as a percentage from 0 to 100. | |
| min_engagement_rate | No | Minimum engagement rate as a percentage from 0 to 100. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds valuable context about dual routing: it can return either autocomplete-style lookup results or legacy semantic results depending on the query, and it preserves backward compatibility with legacy fields. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured with a clear purpose, usage guidance, examples, and return-value notes. Every section carries useful information for a tool with dual behavior; minor redundancy could be tightened but complexity justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 12 parameters, dual routing, existing output schema, and rich annotations, the description is highly complete. It explains return types, downstream tool chaining, and the legacy fallback behavior, giving an agent all context needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 12 parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics by explaining when to use query_type 'creator_lookup' versus 'semantic_discovery' and showing examples with exact query strings. However, the schema's query description contradicts the tool's purpose by saying 'do not pass exact handles or usernames here', which the description does not explicitly correct, creating some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool finds a creator by name/handle while also preserving legacy semantic search. It distinguishes from siblings by explicitly naming get_profile for exact handles on specific platforms and semantic_search_creators for topical discovery, and it provides illustrative examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use as the default creator lookup for creator-ish strings, prefer get_profile for exact handles on a specific platform, and prefer semantic_search_creators for new topical/niche discovery. Concrete examples map user requests to the correct tool and query_type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic discovery search for influencers/content creators using natural-language queries.
Use this only when the user asks to discover creators by topic, audience, geography, niche, content style, or campaign criteria (e.g., "fitness creators in NYC", "vegan recipe creators with high engagement", "tech reviewers who cover phones"). The query is matched against creator profiles, extracted facts, and visual style via hybrid vector search.
Do not use this for exact handles, usernames, or known creator names. If the user gives
a specific platform and handle (for example "@niickjackson on Instagram"), use
get_profile first. For rough name/handle lookup, use search_creators. For
multiple known handles, use lookup_profiles. Semantic search can return lookalike
or topical matches and is allowed to miss an exact username.
Examples:
User: "Find news creators with 1M+ followers" -> use this tool.
User: "Find creators in LA who make cinematic travel videos" -> use this tool.
User: "Pull @niickjackson on Instagram" -> use get_profile, not this tool.
User: "Is @niickjackson a fit for Pixel?" -> use get_profile first, optionally
get_posts, then match_creators.
Returns a ranked list of creators (id, platform, username, follower count, engagement rate, top categories, evidence facts). Use the flat follower, engagement-rate, and verified fields to constrain results when the user gives concrete numeric constraints.
Use find_lookalike_creators instead when you want creators SIMILAR to known ones.
Use match_creators when you want to SCORE specific creators against a brief.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return. | |
| query | Yes | Natural-language semantic discovery query by topic, niche, audience, geography, or content style. Do not pass exact handles or usernames here; use get_profile, lookup_profiles, or autocomplete_creators instead. | |
| verified | No | When set, only return verified or unverified creators. | |
| platforms | No | Platforms to search. Omit for all. | |
| creator_kinds | No | Optional creator kind filter. Omit for no creator-kind filter. | |
| max_followers | No | Maximum follower count. | |
| min_followers | No | Minimum follower count. | |
| max_engagement_rate | No | Maximum engagement rate as a percentage from 0 to 100. | |
| min_engagement_rate | No | Minimum engagement rate as a percentage from 0 to 100. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| data | No | |
| count | No | |
| results | No | |
| has_more | No | |
| not_found | No | |
| next_cursor | No | |
| suggested_followups | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: it explains the hybrid vector search mechanism, states that results may be lookalike/topical matches, and acknowledges that exact usernames may be missed. It also advises using flat numeric fields to constrain results, which clarifies expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured and every sentence earns its place. It opens with a clear purpose, gives concrete usage rules, includes illustrative examples with user queries, and differentiates from siblings. The examples are compact and highly informative, making the length appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, its 9 parameters, and a rich sibling landscape, the description is complete. It covers the query semantics, return value summary, filtering approach, and exclusions, and it complements the existing output schema and annotations. No critical usage context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the nature of the query parameter (natural-language, topic-based) and by explicitly instructing to use the flat follower, engagement-rate, and verified fields for numeric constraints. This enriches parameter understanding, though the schema already documents each parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Semantic discovery search for influencers/content creators using natural-language queries.' It clearly distinguishes itself from sibling tools by explicitly naming alternatives like get_profile, search_creators, lookup_profiles, find_lookalike_creators, and match_creators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this only when the user asks to discover creators by topic, audience, geography, niche, content style, or campaign criteria.' It also gives explicit when-not-to-use instructions and names alternative tools for exact handle lookup, similar-creator search, and scoring creators against a brief.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0autocomplete_creatorsfind_lookalike_creatorsget_creatorget_instagram_postget_instagram_post_transcriptget_instagram_post_transcriptsget_instagram_postsget_postsget_profileget_sample_creatorlookup_profilesmatch_creatorssearch_creatorssemantic_search_creatorsScored across 14 tools
Tools are well-disambiguated with explicit usage guidance in each description, contrasting with others. However, some overlap between search_creators and semantic_search_creators remains due to backward compatibility.
Tool names follow a consistent verb_noun pattern (e.g., autocomplete_creators, get_creator). Instagram-specific tools use a predictable get_platform_type pattern, with minor variants for plurality.
14 tools is well-scoped for a creator discovery and data retrieval platform, covering search, profile lookup, posts, and matching without being excessive.
Covers most creator lifecycle operations (discover, retrieve, match, posts), but lacks cross-platform post retrieval beyond Instagram and advanced analytics tools.
Creator discovery & analytics across YouTube, Instagram, TikTok (30M+) + brand/sponsor intel.
Manage 230M+ influencers, track campaigns, and access real-time CIMS analytics via AI agents
AI influencer search on TikTok, Instagram, YouTube. Deinai MCP token required; credits per result.
Find viral outlier posts on TikTok, Instagram and YouTube, pull creator stats, and crawl on demand.
