Tools - Rep Data Documentation

The server exposes twelve tools that your AI assistant chooses based on your ask. Knowing what is available helps you work with your AI assistant to be more productive.

Read tools

Read tools are always safe: they look things up and never change anything.

Tool	What it does
`list_projects`	Lists the projects you can see, with their names, numbers, and managers
`list_surveys`	Lists surveys with their full setup, quota fill, and live fielding performance — entrants, terminates, completes, realized incidence and interview length, and cost.
`list_users`	Lists the users on your account
`list_accounts`	Lists the account you have access to
`list_definitions`	Lists every valid configuration value: countries and languages, time zones, survey statuses, pacing options, device types
`list_qualifications`	Lists every targeting question and its answer options for a given country and language
`list_responses`	Lists respondent-level responses for a survey: each response’s RDUD, status, reconciliation status, CPI, qualification answers, and the quotas it counted toward. Filter by status or by specific RDUDs

Write tools

Write tools create or modify records. All five use the same safety handshake that’s enforced by the server: the first call returns a plain-language preview of the pending change and applies nothing; the change executes only when it’s confirmed. There are no delete operations.

Tool	What it does
`create_project`	Creates a project. Needs an account, a project manager, a project name, and a project number (unique within the account)
`update_project`	Changes a project’s name, project number, project manager, or business unit. The owning account can’t be changed
`create_survey`	Creates a survey under a project, with its configuration (country, language, LOI, incidence, pricing, entry link, close date) and targeting quotas. New surveys always start in Draft status.
`update_survey`	Changes a survey, including its status (`Live` to launch, `Paused` to pause), settings, quotas, etc.
`update_response`	Reconciles a single complete by marking it `Accepted` (billable) or `Rejected` (not billed). Needs the survey ID, the response’s RDUD, and the reconciliation outcome

Need to know

Everything runs with your permissions. If you can’t see or edit something in the Research Desk UI, your assistant can’t either.
One country, one language per survey. For multi-market studies, create a survey per market like you would in the UI or API.
Quotas control fielding, not the respondents count. The respondent target is informational; the quota caps are what actually govern who qualifies and how many complete.
Targeting IDs are country-specific. Qualification and answer-option IDs differ by country and must come from list_qualifications for the market you’re targeting. There are no ranges — ages 18–21 are [18, 19, 20, 21], never "18-21".
Set the entry link explicitly. The survey entry_link must be your real survey URL and must contain the [%RDUD%] variable, which Research Desk replaces with a unique respondent ID for tracking and reconciliation.
Quota updates replace the whole set. When updating a survey’s quotas, the list you send becomes the survey’s quota set and quotas left out are removed. Always send the complete intended set.
Only completes are reconciled. Completes are billable by default. Any complete you don’t reject before the deadline is auto-accepted and billed. See the Reconciliation guide for the full process.
Reconciliation closes at the end of the following month. You can reconcile a complete until the last day of the month after the month it completed (for example, a December complete can be reconciled through January 31). Unprocessed completes are auto-accepted the next day, and changes after the deadline are blocked.
You can change a decision before the deadline. Re-run update_response with the other outcome to switch a complete between Accepted and Rejected. Moving a complete back to Unprocessed (Clear) is only available in the Research Desk UI.
Reconciliation is one response per call. update_response accepts or rejects a single RDUD, and each one gets its own preview and confirmation. For large reconciliation files, use the Demand API or Research Desk UI.
Reconciliation is asynchronous. A confirmed update_response is queued, not applied instantly, so list_responses may show the old reconciliation status for a short time.
Response lists are paginated. list_responses returns 50 responses per page by default. Valid response and reconciliation statuses come from list_definitions.

​Read tools

​Write tools

​Need to know

Read tools

Write tools

Need to know