Desearch

People Search

people-search

Start a paid job billed to the user's Desearch balance: find people on X, YouTube, LinkedIn, or TikTok who match a plain-language description. Returns a task_id at once, with the task's status and reserved_cost_usd. Cost: the call reserves count times the platform's per-person price at the time of the call (reserved_cost_usd; prices at https://desearch.ai/pricing). When the search ends you pay only for the people it delivered (final_cost_usd; a per-search minimum applies when it finds anyone; a search that finds no one is free) and the rest of the reservation is returned. Data: each person comes back with a fit score, why they matched, their audience, and only the contacts and links they list publicly. Desearch reads public data only. X: public posts and public profile fields (bio, followers, website, location). YouTube: public channel pages (About section, subscribers, country, links) and the creator's own website for publicly listed contact details. LinkedIn: public posts and public profiles (headline, company, location, followers, about). TikTok: public videos and public profiles (bio, followers, likes, latest videos, a public email listed in the bio). People found stay readable for 30 days after the search ends. The search runs in the background, usually for 1 to 5 minutes: poll people-search-status with the task_id to read progress and the people found so far, and use people-search-pause, people-search-resume, or people-search-cancel to pause, resume, or cancel it. Do not start the same search twice; send idempotency_key so a retry returns the first task instead of charging again. Filters depend on the platform. x: min_followers, max_followers, verified_only, countries, keywords, exclude_keywords. youtube: min_subscribers, max_subscribers, countries, require_contact, keywords, exclude_keywords. linkedin: min_followers, max_followers, countries, keywords, exclude_keywords. tiktok: min_followers, max_followers, require_contact, keywords, exclude_keywords.

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": {
      "platform": "<platform>",
      "query": "<query>"
    },
    "name": "people-search"
  }
}

Input Schema

Name	Required	Description
`count`	No	How many qualified people to find (5-200, API default 25). The search reserves this many and bills only the people it delivers.
`query`	Yes	Who you are looking for, in plain language, example: 'Skincare creators who review sunscreen'.
`exclude`	No	Handles to leave out, for example people you already contacted.
`keywords`	No	Words that should appear in their posts, videos, or bio. All platforms.
`metadata`	No	Your own labels for this search, example: {"campaign": "q4-outbound"}. Up to 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.', '-'; values are strings of up to 200 characters. Returned on the task; filter people-search-tasks by it. The search does not use it.
`platform`	Yes	Where to look: 'x' (X profiles), 'youtube' (YouTube creators), 'linkedin' (LinkedIn members), or 'tiktok' (TikTok creators).
`countries`	No	Countries to prefer, example: ['US', 'GB']. x, youtube, linkedin.
`min_score`	No	Only return people with at least this fit score (0-100).
`max_followers`	No	Maximum follower count. x, linkedin, tiktok.
`min_followers`	No	Minimum follower count. x, linkedin, tiktok.
`verified_only`	No	Only verified or X Premium accounts. x only.
`idempotency_key`	No	Any unique string for this search, for example a UUID. Sending the same key again returns the first task and is not charged again.
`max_subscribers`	No	Maximum subscriber count. youtube only.
`min_subscribers`	No	Minimum subscriber count. youtube only.
`require_contact`	No	Only creators with a public email (tiktok: in the bio; youtube: an email or contact link). youtube, tiktok.
`exclude_keywords`	No	Leave out people who mention these words. All platforms.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

addedInput schema / properties / metadata

Added value: +{
+  "additionalProperties": {
+    "maxLength": 200,
+    "type": "string"
+  },
+  "description": "Your own labels for this search, example: {\"campaign\": \"q4-outbound\"}. Up to 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.', '-'; values are strings of up to 200 characters. Returned on the task; filter people-search-tasks by it. The search does not use it.",
+  "type": "object"
+}

AddedOct 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations by disclosing the full billing model (reservation via reserved_cost_usd, final_cost_usd, per-search minimum, free when nothing is found, refund of the remainder), the 30-day readability window, and per-platform data sourcing with a 'public data only' guarantee. The idempotency caveat is consistent with idempotentHint=false: without a key, a retry charges again.

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 purpose and cost, then data, retention, async workflow, idempotency, and filters in a logical order. It is dense as a single unbroken block and the per-platform data-source inventory (bio, followers, About section, country, links) is longer than an agent needs to choose the tool, so it stops short of zero-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?

For a 16-param, costly, asynchronous, open-world tool with no output schema, it covers everything an agent needs: what it returns at submit time (task_id, status, reserved_cost_usd), how to read results, cost exposure, data provenance, and result lifetime. Nothing decision-relevant is missing.

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 value by consolidating which filters apply to which platform (min_followers only on x/linkedin/tiktok, min_subscribers only on youtube, verified_only x-only) and by explaining that count drives the reservation while billing is per delivered person. The filter matrix largely restates the schema's per-param notes, so it is reinforcement rather than new meaning.

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 — 'find people on X, YouTube, LinkedIn, or TikTok who match a plain-language description' — and frames it as a paid async job, which cleanly separates it from the people-search-status/pause/resume/cancel siblings it names. An agent can tell what this does without opening the schema.

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?

Explicitly routes the agent: poll people-search-status with the task_id, use pause/resume/cancel for lifecycle control, and 'Do not start the same search twice; send idempotency_key' so retries don't re-charge. It also states the expected 1-5 minute runtime, which tells the agent not to block.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Desearch tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.