Skip to main content
Glama
junetic

mcp-usercall

by junetic
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Usercall MCP - AI agents that run real user interviews

npm License

AI can build products. But it still doesn't talk to users.

Give your AI agents the ability to ask real users why.

Usercall MCP runs AI-moderated voice or text interviews with real users. Use it to learn why users churn, where onboarding drops off, or why an action failed, and get themes, insights, and verbatim quotes.

Why this exists

AI agents can now build and ship products extremely quickly.

But most agents still rely on synthetic feedback or assumptions about users.

Usercall MCP lets agents gather real qualitative feedback directly from users.

Related MCP server: gq-insight-mcp

Choose a connection

Recommended: hosted MCP (Claude, ChatGPT, Cursor, Grok Bot)

Add https://mcp.usercall.co as a remote MCP connector / custom connector.

  • OAuth sign-in (no API key, no npx)

  • Same tools as this package (studies + Research Triggers)

  • Docs: app.usercall.co/docs/mcp

  • Cursor Directory / Grok Bot: this repo ships .mcp.json so cursor.directory can install the hosted connector. Grok Bot cannot run the local npx package.

This package: local / API-key / machine-to-machine

Use @usercall/mcp over stdio when you want a Bearer API key (scripts, local clients, M2M).

  1. Sign in at app.usercall.co → Home → Developer → Create API key

  2. Run npx -y @usercall/mcp with USERCALL_API_KEY

Example workflow

Agent: "Why are users confused about onboarding?"

→ create_study
→ share interview_link with users
→ get_study_results

The returned interview_link can be shared with participants through email, Slack, Discord, or in-product prompts.

Example result:

{
  "themes": [
    {
      "name": "Onboarding confusion",
      "summary": "Users struggled to understand the second step.",
      "quotes": [
        "I wasn't sure what the app was asking me to do.",
        "I didn't know I had to verify my email before continuing."
      ]
    },
    {
      "name": "Pricing confusion",
      "summary": "Free plan limits were not clearly communicated.",
      "quotes": ["I wasn't sure if the free plan included analytics."]
    }
  ]
}

How it works

AI Agent

↓

Usercall MCP (hosted OAuth or this stdio package)

↓

Usercall Agent API

↓

Real user interviews

↓

Themes and verbatim quotes returned to the agent

With Research Triggers, the agent can also target users in your product:

Analytics MCP (PostHog, Mixpanel, …) finds a behavior

↓

Usercall MCP creates a study and a paused Research Trigger

↓

You activate it in Usercall

↓

The Usercall SDK invites matching users to an interview right after the behavior

Research Triggers

Analytics tells an agent what users do. Research Triggers let it ask them why.

User:  "Look at our PostHog data and find something worth investigating."

Agent (PostHog MCP):  users who test a study rarely launch one.

Agent (Usercall MCP):
  list_trigger_events()                  → study_tested, study_launched, …
  get_trigger_event_schema("study_tested")
                                         → properties: source, interview_type
                                           traits: plan ("free", "pro"), account_type
  create_study(...)  or  list_studies()
  create_research_trigger({
    study_id, event_name: "study_tested",
    traits: { plan: "free" }, sampling_percent: 25, max_invites_per_day: 10
  })                                     → status: "paused", summary, activation_url

Agent: "I've prepared a Research Trigger. When: study_tested · Audience: plan = free ·
        25% sampled · max 10 invites/day. It's paused. A human activates it here: <activation_url>"

  • The Usercall SDK has to be installed. If list_trigger_events returns nothing, call get_trigger_sdk_setup (with your analytics provider and event names) to get the snippet. Coding agents can install it for you.

  • Only events Usercall has actually received can be used. Filters are exact matches on event properties or user traits. get_trigger_event_schema shows which field is which.

  • Unsupported conditions are rejected, not silently dropped. These include event counts, sequences, absence ("did not do X"), time windows, and not-equals. get_trigger_capabilities returns the full list.

Local install (API key)

1. Get an API key

Sign in at app.usercall.co → Home → Developer → Create API key

2. Add to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "usercall": {
      "command": "npx",
      "args": ["-y", "@usercall/mcp"],
      "env": {
        "USERCALL_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "usercall": {
      "command": "npx",
      "args": ["-y", "@usercall/mcp"],
      "env": {
        "USERCALL_API_KEY": "your_key_here"
      }
    }
  }
}

For Claude, ChatGPT, or Cursor remote connectors, prefer https://mcp.usercall.co instead of this JSON config.

Restart your MCP client.

3. Ask your agent

Run user interviews to understand why users drop off during onboarding.

Context:
- B2B SaaS product
- 3-step signup flow

Goal:
Identify confusion points and friction.

Target interviews: 5
Language: ko
Interview mode: voice

Show participants this prototype during the interview:
https://www.figma.com/proto/abcd1234/onboarding-flow

The agent will:

  1. create a study

  2. return an interview link

  3. collect responses

  4. return the summary (themes, insights, and risks)

Structured tool example

Equivalent create_study tool call:

create_study
key_research_goal: "Understand why users drop off during onboarding"
business_context: "B2B SaaS signup flow"
target_interviews: 5
languages: ["en"]
interview_mode: "voice"

study_media:
  type: "prototype"
  url: "https://www.figma.com/proto/abcd1234/onboarding-flow"
  description: "New onboarding flow concept"

Tools

create_study

Create an AI-moderated interview study to learn why users churn, drop off in onboarding, fail an action, or where a product assumption is wrong. Returns study_id and interview_link for a voice, text, or voice-and-text interview. key_research_goal is required and cannot be changed later. business_context is optional. Defaults: target_interviews 1, duration_minutes 12, interview_mode voice. One active agent study per account. Does not run the interview or invite a participant. HTTP 402 includes checkout_url.

Field

Type

Required

Default

key_research_goal

string (5–2000)

yes

business_context

string (5–2000)

no

additional_context_prompt

string

no

target_interviews

number (1–200)

no

1

languages

string[]

no

duration_minutes

number (5–65)

no

12

interview_mode

voice | text | voice_and_text

no

voice

voice_gender

female | male

no

enable_link_context

boolean

no

custom_link_variables

{ key, label?, default_value? }[]

no

metadata

object

no

study_media

object

no

One locale turns the language picker off; two or more turn it on. Research goal cannot be changed after create.

study_media (optional). Visual stimulus shown during all interview questions:

Field

Type

Required

type

image | prototype

yes

url

string (URL)

yes

description

string (max 500 chars)

no

  • image: Direct image URL (.png, .jpg, .gif, .webp)

  • prototype: Figma prototype URL (converted to interactive embed)

  • Media is only visible to web participants; phone callers won't see it

update_study

Update an interview study: slots, guide questions, intro, languages, voice, or an image or Figma prototype shown to participants. Returns the updated study. key_research_goal cannot be changed. is_link_disabled true stops new interviews and keeps recordings. One locale hides the language picker; two or more show it. Query parameters on interview_link are ignored until enable_link_context is true. study_media null clears media. API errors include http_status. Does not dry-run the guide or invite a participant.

Field

Type

Required

study_id

uuid string

yes

target_interviews

number (1–200)

no

is_link_disabled

boolean

no

ai_agent_intro_message

string

no

key_learning_goals

string

no

workflow_end_message

string

no

workflow_questions

{ text, ... }[]

no

interview_mode

voice | text | voice_and_text

no

languages

string[]

no

voice_gender

female | male

no

enable_link_context

boolean

no

custom_link_variables

{ key, label?, default_value? }[]

no

study_media

object or null

no

Pass study_media: null to clear media. The study_media object follows the same schema as in create_study.

get_study_status

Check whether user interviews are still running, being analyzed, or complete. Returns completed_interviews, target_interviews, interview_link, and next_step. running and analyzing include no findings, themes, or quotes. Does not change the study.

Field

Type

study_id

uuid string

Status values: running · analyzing · complete

Response includes interview progress fields, including completed_interviews and target_interviews.

get_study_results

Get interview findings after real users have talked: themes, insights, risks, and verbatim quotes. format omitted or summary returns themes, insights, and risks. format=full also returns transcripts. Empty themes mean analysis is not ready. Does not create interviews or edit the guide.

Field

Type

Required

study_id

uuid string

yes

format

summary | full

no

Summary/full responses include study progress fields and analysis output.

simulate_interview

Dry-run an interview guide before a real participant joins, including a question about churn, onboarding, or a failed action. Omit simulation_id to start; returns immediately with status running and a simulation_id. Pass simulation_id to read that run. Result status is pass, fail, or error. Max 5 simulations per account per UTC day. HTTP 429 means the daily cap is reached. Optional persona has name and prompt. A dry-run does not change completed_interviews and does not invite a participant.

Field

Type

Required

study_id

uuid string

yes

simulation_id

uuid string

no

persona

{ name, prompt }

no

Omit simulation_id to POST /api/v1/agent/studies/{studyId}/simulations. Pass simulation_id to GET that simulation. The tool does not poll.

review_study

Review an interview guide and return a written critique of the questions before real users see them. Reads the guide only: no transcripts, and suggested edits are not applied. Costs 1 credit. Request is study_id only; call_ids are not accepted. Works when the in-app review control is hidden. HTTP 402 includes checkout_url. Does not return themes, quotes, or other findings.

Field

Type

Required

study_id

uuid string

yes

Sends study_id only. It does not send call_ids.

delete_study

Permanently delete an interview study, its recordings, and unused reserved credits. Cannot be undone. Does not delete in-product research triggers.

Field

Type

Required

study_id

uuid string

yes

Research Trigger tools

Tool

Purpose

get_trigger_capabilities

Which in-product trigger conditions work. One event, exact property or trait, URL rule, page dwell. No counts, sequences, absence, time windows, or not-equals

get_trigger_sdk_setup

Snippet for product events (failed action, onboarding, churn). install_snippet, identify_snippet, allowlist_update_snippet. No secret keys

list_trigger_events

Product event names from the last 30 days. A trigger accepts only an observed name

get_trigger_event_schema

Fields on one product event, with types and sample values. Exact, case-sensitive, type-sensitive

list_studies

Existing interview studies: study_id, interview_link, interview_mode, trigger_eligible

create_research_trigger

Paused invite after a product moment (failed action, churn, onboarding). Returns activation_url

list_research_triggers

In-product triggers with status and activation_url

get_research_trigger

One trigger: who it invites, activation_url, invite and interview counts. No themes or quotes

update_research_trigger

Who gets invited. status: "active" is rejected (409). Editing an active trigger pauses it

delete_research_trigger

Permanently delete a trigger. Completed interviews stay on the study

create_research_trigger

Field

Type

Required

Default

study_id

uuid string

yes

event_name

string (from list_trigger_events)

yes

properties

object of exact-match values

no

traits

object of exact-match values

no

url

{ match: equals | contains | starts_with, value }

no

dwell_seconds

1–600 (page-visit triggers only)

no

source

page_visit | analytics_event | custom

no

sampling_percent

1–100

no

100

cooldown_days

0–365

no

30

max_invites_per_day

1–100

no

100

intercept_title

string (≤120), small label above the prompt

no

default

intercept_body

string (≤500), prompt text

no

default

delivery_method

intercept | webhook

no

intercept

webhook_url

public https URL (required for webhook)

no

webhook_secret

string (16–200), HMAC key, write-only

no

invite_link_params

{ static?, from_traits?, from_properties? }

no

name

string (≤100)

no

generated

For page-visit triggers, use source: "page_visit" and event_name: "$pageview", with url and optionally dwell_seconds.

Delivery.

  • intercept (default) shows the Usercall widget in your product, and the user takes a voice or text interview in the page. The modes come from the study; list_studies returns each study's interview_mode.

  • webhook POSTs each matched user to webhook_url, with their user ID, email if known, traits, event properties and a personal interview link. If webhook_secret is set, requests carry an x-usercall-signature HMAC header.

  • Only public https URLs are accepted, and the activation page shows the destination before a person activates the trigger.

Safety

  • Agents cannot activate triggers. Triggers are always created paused. Calling update_research_trigger with status: "active" returns HTTP 409 and the activation_url. A person has to open that link, review who will be invited, what they will see and the credit cost, and click Activate.

  • Changes to an active trigger need re-approval. Changing an active trigger's configuration pauses it again.

  • Secret keys are never returned. The ingestion secret key never comes back from any tool.

Example workflow

1. create_study
   key_research_goal: "Why do users drop off during onboarding?"
   business_context: "B2B SaaS, 3-step signup flow"
   target_interviews: 5
   languages: ["ko"]
   interview_mode: "voice"

   → returns { study_id, interview_link }
   (`business_context` is optional; `key_research_goal` alone still creates a study)

2. simulate_interview
   study_id
   → running, simulation_id
   call again with simulation_id
   → pass, fail, or error

3. review_study
   study_id
   → guide check only; write changes with update_study

4. Share interview_link with participants
   (email, Slack, in-product prompt, etc.)

5. get_study_status
   → "analyzing"

6. get_study_results
   → summary: themes, insights, and risks
   use format=full only for a quote

With visual stimulus

1. create_study
   key_research_goal: "Get feedback on new dashboard design"
   business_context: "Redesigning analytics dashboard for power users"
   study_media:
     type: "image"
     url: "https://example.com/dashboard-mockup.png"
     description: "New dashboard design concept"

   → returns { study_id, interview_link }

2. After simulate_interview passes, a human shares interview_link. Participants see the mockup during the interview.

For Figma prototypes, use type: "prototype" with a Figma proto URL.

Requirements

  • Node.js 18+

  • A valid Usercall API key (local / API-key path only)

Self-hosting / development

pnpm install
pnpm build
USERCALL_API_KEY="your_key_here" pnpm start

Tests and smoke tests:

pnpm test                                   # unit + MCP contract tests
USERCALL_API_KEY="your_key_here" pnpm smoke # creates a real study
USERCALL_API_KEY="your_key_here" SMOKE_STUDY_ID="<uuid>" SMOKE_EVENT_NAME="<observed event>" pnpm smoke:triggers

Official MCP Registry

Usercall is listed on the Official MCP Registry as co.usercall/mcp.

Troubleshooting

Error

Fix

Missing USERCALL_API_KEY

Set the env var before starting this stdio package

401 Unauthorized

Invalid or revoked API key

402 Insufficient credits

Open the returned checkout_url, or add credits at app.usercall.co

500 on create

Verify your key has access to Agent API v1

event_not_observed

Usercall hasn't received the event. Add it to your SDK allowlist (get_trigger_sdk_setup(events=[...])), trigger it in your app, then retry

wrong_placement

The field is a trait, not a property (or the reverse). Use the suggested fix in the error

Trait filters never match

Call window.usercall.identify({ userId, traits }) when the user is known (see identify_snippet)

webhook_url_not_allowed

Use a public https URL, without credentials; localhost and private IPs are rejected

409 activation_required

Expected: agents can't activate. Share activation_url with the user

429 on simulate_interview

Cap is 5 simulations per account per UTC day. Stop for the day

Active trigger never fires

Check the event is still arriving (list_trigger_events), and check the values match exactly (case and type)

Remote Claude / ChatGPT / Cursor connectors should use https://mcp.usercall.co (OAuth). This package is the API-key stdio path.

License

MIT

Available Tools

5 tools
create_studyAInspect

Creates a user interview study and returns an interview_link to share with participants. Starts with 1 interview slot. Optionally include study_media to show an image or Figma prototype during the interview.

ParametersJSON Schema
NameRequiredDescriptionDefault
key_research_goalYes
business_contextYes
additional_context_promptNo
languageNo
duration_minutesNo
metadataNo
study_mediaNoVisual stimulus shown during all interview questions (web participants only)

TDQS

A3.8/5.0
Behavior4/5

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

No annotations provided, so description carries full disclosure burden. Successfully discloses return value ('interview_link'), side effect ('Starts with 1 interview slot'), and optional media behavior. Missing: auth requirements, rate limits, or error conditions (e.g., duplicate study names).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences. First establishes core operation and return value; second covers default slot count and key optional feature. No redundant phrases or tautology despite null title.

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

Completeness3/5

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

Explains return value (interview_link) compensating for missing output schema, and covers the nested study_media object. However, for 7 parameters with 86% lacking schema descriptions, description omits explanation of required parameters' semantics and relationships between context / research goals.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 14% (only study_media described at top level). Description mentions study_media functionality but fails to compensate for 6 undocumented parameters including required fields (key_research_goal, business_context). Does not explain what content belongs in research goals vs business context.

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?

Specific verb ('Creates') + specific resource ('user interview study') clearly identifies the operation. Implicitly distinguishes from siblings delete_study/update_study through the creation verb, and from get_* tools by specifying it returns an interview_link.

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

Usage Guidelines3/5

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

Implies creation use case through verb choice and mentions it 'Starts with 1 interview slot,' suggesting initialization behavior. However, lacks explicit guidance on when to use update_study instead, or prerequisites for creation (e.g., workspace requirements).

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

delete_studyAInspect

Permanently deletes a study and all associated data. Releases unused reserved credits.

ParametersJSON Schema
NameRequiredDescriptionDefault
study_idYes

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations provided, the description carries full behavioral disclosure burden. It succeeds by warning of irreversibility ('Permanently'), scope of destruction ('all associated data'), and economic side effects ('Releases unused reserved credits'). Deducted one point for not indicating failure behavior (e.g., what happens if study_id doesn't exist).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Critical information ('Permanently') front-loaded. First sentence covers the core operation; second sentence covers the credit side effect. No redundancy or generic filler.

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

Completeness3/5

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

Covers the essential risks (destruction, credits) for a destructive tool with no output schema. However, missing error handling patterns (404 behavior), authorization requirements, or confirmation requirements prevents a higher score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to compensate. It fails to mention the study_id parameter, its expected format (UUID), or how to obtain it, even though this is the sole parameter. While somewhat inferable from the tool name, the description adds zero semantic value beyond the schema structure.

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?

Excellent specificity: 'Permanently deletes' provides a precise verb, 'study' identifies the resource, and 'all associated data' clarifies scope. The description clearly distinguishes this from sibling tools like update_study (modification vs destruction) and get_* (read-only).

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

Usage Guidelines3/5

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

The word 'Permanently' implicitly signals this is for complete removal, not modification (update_study) or creation (create_study). However, it lacks explicit guidance on when to prefer deletion over archival, or prerequisites like 'study must be in terminal state'.

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

get_study_resultsCInspect

Returns analysis results. When presenting results, always quote specific participant responses verbatim using the quotes field in each theme.

ParametersJSON Schema
NameRequiredDescriptionDefault
study_idYes
formatNo

TDQS

C2.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It partially succeeds by revealing the result structure contains 'themes' with 'quotes fields', hinting at a nested qualitative data format. However, it omits critical operational details: whether this is read-only (implied by 'Returns' but not confirmed), caching behavior, result size limits, or latency characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief (two sentences), but awkwardly mixes concerns: the first states functionality tersely ('Returns analysis results'), while the second jumps to post-invocation presentation guidelines. This structural confusion places output formatting instructions in a field meant for capability description, creating a minor organizational misfit despite brevity.

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

Completeness3/5

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

Given the absence of an output schema, the description partially compensates by describing the result contents (themes containing quote fields), which helps the agent understand what data structure to expect. However, with zero annotations and zero parameter schema coverage, significant gaps remain for a complete invocation context, particularly regarding the optional 'format' parameter's impact on result granularity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description text compensates not at all. Neither 'study_id' (despite being a required UUID) nor 'format' (despite having enum values 'summary'/'full' with unclear semantic differences) are mentioned in the text. The agent must rely solely on parameter names, which is insufficient for the 'format' option distinctions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it 'Returns analysis results' which is vague, though the mention of 'participant responses', 'themes', and 'quotes field' provides domain context about qualitative research data. However, it fails to distinguish clearly from sibling 'get_study_status' (which likely returns metadata vs. actual results), leaving ambiguity about which tool retrieves substantive data versus operational status.

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

Usage Guidelines2/5

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

No explicit guidance is provided on when to use this tool versus alternatives like 'get_study_status' or 'create_study'. The second sentence provides presentation instructions ('always quote specific participant responses verbatim') rather than invocation guidelines, failing to clarify prerequisites or selection criteria.

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

get_study_statusDInspect
ParametersJSON Schema
NameRequiredDescriptionDefault
study_idYes

TDQS

D1/5.0
Behavior1/5

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

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

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

Completeness1/5

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

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

update_studyBInspect

Updates an existing study. Use this to increase interview slots, add/update media, or modify the interview guide.

ParametersJSON Schema
NameRequiredDescriptionDefault
study_idYes
target_interviewsNoTotal number of interview slots for this study.
is_link_disabledNo
study_mediaNoVisual stimulus shown during all interview questions (web participants only)

TDQS

B3.3/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. States it's an update operation but lacks critical behavioral details: partial vs full replacement, validation rules, error handling for non-existent studies, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Front-loaded with main action ('Updates'), followed by specific use cases. Every word earns its place.

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

Completeness3/5

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

With no annotations, no output schema, and 50% param coverage, gaps remain. Description covers primary use cases but doesn't compensate for missing behavioral details or undocumented parameters. Adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (target_interviews and study_media have descriptions; study_id and is_link_disabled do not). Description maps use cases to the two documented parameters but fails to explain the undocumented boolean 'is_link_disabled' or required 'study_id'. Baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb ('Updates') and resource ('existing study'). Lists specific use cases (interview slots, media). Distinguishes from siblings implicitly (update vs create/delete/get), though 'modify interview guide' doesn't map clearly to any schema parameter.

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

Usage Guidelines3/5

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

Provides specific usage scenarios ('Use this to increase interview slots...'), but lacks explicit differentiation from siblings (e.g., when to use create_study vs this) and no guidance on when not to use the tool.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.1
    • First observedcreate_study
    • First observeddelete_study
    • First observedget_study_results
    • First observedget_study_status
    • First observedupdate_study
Deploy Server
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

TDQS

C2.9/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting different aspects of study management: create, delete, get results, get status, and update. There is no overlap in functionality, and the descriptions clearly differentiate their roles, making it easy for an agent to select the correct tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., create_study, delete_study, get_study_results, get_study_status, update_study). This predictability enhances readability and usability, with no deviations in naming conventions.

Tool Count5/5

With 5 tools, the server is well-scoped for managing user interview studies. Each tool earns its place by covering essential CRUD operations and status/results retrieval, avoiding bloat while providing complete functionality for the domain.

Completeness4/5

The tool set offers strong coverage for study lifecycle management, including create, read (results and status), update, and delete. A minor gap exists in the lack of a tool for listing or searching studies, which could limit discovery in scenarios with multiple studies, but core workflows are well-supported.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers