Explore your user test data, summarize feedback, and uncover actionable insights faster. Ask questions about tests, participants, tasks, and findings in plain language.
Scored across 5 tools
Each tool targets a distinct sub-resource (insights, tasks, test detail, videos, test list), and descriptions explicitly cross-reference list_tests and get_tasks for prerequisite context. The only mild overlap is between get_insights and get_videos with includeNotesAndClips/includeTranscript, since both surface observation-level content, and get_test partially duplicates the tester/video counts returned by get_videos.
Uniform snake_case verb_noun pattern: get_insights, get_tasks, get_test, get_videos, list_tests. The single list_ vs get_ distinction is intentional and semantically meaningful (collection vs single resource).
Five tools is well within the ideal range and every tool maps to a distinct read operation in the test-analysis workflow. None appears redundant or filler; the surface is tight and purposeful.
The read/analysis lifecycle is well covered: list tests, inspect a test, resolve its task steps, pull tester videos, and retrieve auto-generated insights, with resolution hints between steps. Gaps are minor but real — no create/update for tests and no direct single-video lookup by id, so the surface is read-only.
Get the insights for one Userbrain test by its id. Insights are findings of interest that Userbrain automatically generates by analyzing all of the test's tester (think-aloud) videos — recurring observations, usability issues, and themes across the sessions, each with a short summary and supporting video clips/notes. Returns the insights as text and structured data (no interactive UI). Use list_tests first to find the testId.
| Name | Required | Description | Default |
|---|---|---|---|
| testId | Yes | The numeric id of the test (from list_tests). |
| Name | Required | Description |
|---|---|---|
| testId | Yes | |
| insights | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/non-destructive/closed-world, and the description adds real context beyond them: insights are automatically generated from all tester videos, and results come back as text plus structured data with no interactive UI. It does not cover latency, empty-result behavior, or cost of generation, so it falls short of 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?
Three sentences, front-loaded with the action and the prerequisite placed last where it belongs. The middle sentence on what insights contain is somewhat long but earns its place by preventing misuse of the tool; no filler.
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?
An output schema exists, so return values need not be spelled out, yet the description still characterizes the payload (text + structured data, no UI). The main remaining gap is edge-case behavior — what is returned when insight generation is pending or empty — which is worth a line but not critical.
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% and the schema itself already says the id comes from list_tests, so the description's 'by its id' and list_tests hint largely restate structured data. Baseline 3 is correct for a single fully-documented parameter.
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?
States a specific verb and resource ('Get the insights for one Userbrain test by its id') and then defines what an insight actually is — auto-generated findings from tester think-aloud videos with summaries and supporting clips. This clearly separates it from sibling tools like get_test, get_videos, and get_tasks.
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?
Gives an explicit prerequisite: 'Use `list_tests` first to find the `testId`', which routes the agent to the correct discovery tool. It does not, however, say when to prefer get_insights over get_videos or get_test, or what to do if a test has no insights yet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the tasks (test steps) of a Userbrain test by its id. These are the instructions the customer set up that testers (participants) work through during the unmoderated study — typically task prompts and questions. Each step has a teststep id (the same id that get_videos task responses reference, so use this tool to resolve those ids to their instructions), a type, the instruction text (task), and a response count. Returns the tasks as text and structured data (no interactive UI). Use list_tests first to find the testId.
| Name | Required | Description | Default |
|---|---|---|---|
| testId | Yes | The numeric id of the test (from list_tests). |
| Name | Required | Description |
|---|---|---|
| tasks | Yes | |
| testId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, non-destructive, closed-world profile, so the description earns credit for extra context: it discloses the shape of each returned step (teststep id, type, instruction text, response count) and that output is text + structured data with no interactive UI. The id-provenance link to get_videos is genuinely useful behavior an agent could not infer from 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?
Purpose is front-loaded in the first sentence, followed by only relevant elaboration on structure, id resolution, and prerequisite. The parenthetical explanation is slightly long, but every sentence carries information an agent needs.
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 one-param tool is fully covered: prerequisite (list_tests), id resolution across tools, and content of returned steps are all stated. An output schema exists, yet the description still adds the cross-tool id mapping that makes the tool usable in context.
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?
With 100% schema coverage and a single required param, the baseline is 3, but the description adds provenance for testId ('from list_tests') and explains that teststep ids returned here are the same ids referenced by get_videos responses, which is meaningful cross-parameter 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?
States a specific verb and resource ('Get the tasks (test steps) of a Userbrain test by its id') and immediately scopes it with what the data actually is. It is clearly distinguishable from siblings like get_test, get_videos, and list_tests.
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?
Gives an explicit entry path ('Use list_tests first to find the testId') and a concrete cross-tool usage rule: use this tool to resolve the teststep ids that get_videos task responses reference. It does not state exclusions (e.g., when get_test alone suffices), so it stops just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the details of one Userbrain test by its id, with an interactive UI. A Userbrain test is one unmoderated usability study — a target URL, language, and task instructions the customer set up, plus the think-aloud videos recorded by the testers (participants) who attempted the task. Returns the test's status, language, target URL, type, and tester/video counts. Use list_tests first to find the testId.
| Name | Required | Description | Default |
|---|---|---|---|
| testId | Yes | The numeric id of the test (from list_tests). |
| Name | Required | Description |
|---|---|---|
| test | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds meaningful behavior beyond that by noting the response renders an interactive UI and enumerating the returned fields (status, language, target URL, type, tester/video counts). It doesn't mention permissions or payload size, keeping it below 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?
Front-loaded with the action and resource, then the domain definition, then the return summary and the routing hint. The definition of a Userbrain test is a little longer than strictly necessary, but it earns its place by disambiguating the resource.
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?
For a single-param, read-only fetch with an output schema already present, the description covers purpose, the prerequisite call, and even previews return fields. Nothing an agent needs in order to invoke it correctly 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% and the single testId parameter is fully documented in-schema, including its provenance from list_tests. The description reinforces that provenance but adds no format or type detail beyond the schema, so the 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?
States a specific verb and resource ('Show the details of one Userbrain test by its id') and goes further to define what a test is (unmoderated study with target URL, language, tasks, videos), which lets an agent distinguish it from aggregate or listing siblings.
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 names the prerequisite/alternative ('Use list_tests first to find the testId'), which is the key routing instruction for this tool. It doesn't mention when to prefer get_insights, get_tasks, or get_videos, so it isn't a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the videos (tester sessions) of a Userbrain test by its id. Each video is one tester's (participant's) think-aloud screen recording attempting the test's tasks. Always returns the tester and their demographics, device, duration, and their answer to each task step (each labeled by its teststep id, e.g. teststep #1065502 — call the get_tasks tool to see what those teststeps actually ask; it returns the test's currently active teststeps with their ids). To keep responses small, the heavy per-session detail is omitted by default: set includeNotesAndClips to also return the notes and clips (observations), and includeTranscript to also return the full think-aloud transcript. Enable these only when that detail is actually needed for the task. Returns text and structured data (no interactive UI). Use list_tests first to find the testId.
| Name | Required | Description | Default |
|---|---|---|---|
| testId | Yes | The numeric id of the test (from list_tests). | |
| includeTranscript | No | Include each video's full think-aloud transcript (can be hundreds of lines per video). Off by default. Set true only when the verbatim transcript is actually needed — e.g. quoting exactly what a tester said. | |
| includeNotesAndClips | No | Include each video's notes and clips — the AI-generated and manual observations on the session. Off by default because it makes the response much larger. Set true only when the detailed observations are actually needed (e.g. summarizing findings or quoting specific moments). |
| Name | Required | Description |
|---|---|---|
| testId | Yes | |
| videos | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/destructive=false; the description goes further, disclosing the default payload shape (heavy per-session detail omitted), what each opt-in flag unlocks, response-size tradeoffs, and that it returns text and structured data with no interactive UI.
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 purpose before the alternative-tool routing and opt-in guidance. Slightly dense with parentheticals but every sentence carries actionable information.
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 annotations, full schema, and an output schema, the description supplies exactly what's missing: default vs opt-in return contents, size tradeoffs, and prerequisite discovery via list_tests.
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 schema carries the flag semantics; the description still adds value by explaining teststep-id labeling and the get_tasks link for resolving them, but largely reinforces what the schema already states.
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?
States a specific verb and resource ('Get the videos (tester sessions) of a Userbrain test by its id') and disambiguates 'videos' as tester think-aloud recordings, which an agent can tell apart from siblings like get_tasks and get_insights.
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 routes the agent: 'Use list_tests first to find the testId', points to get_tasks for teststep meaning, and instructs to enable the heavy flags 'only when that detail is actually needed for the task' with concrete conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's Userbrain tests, with an interactive UI. A Userbrain test is one unmoderated usability study: the customer configures a target URL, language, and task instructions, then orders testers (participants) who record think-aloud videos attempting the task. Tests are returned ordered by most recent activity — the first test in the list is the one with the latest event (e.g. a newly delivered video or a recent change). When the user refers to "the last test", "the latest test", or "the test we just did", they most likely mean the first test in this list. Each test includes its id, title, status, language, target URL, and tester/video counts (video_count is the number of tester videos; new_video_count is how many are newly delivered).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| tests | Yes | |
| ordering | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the ordering rule (most recent activity first) and the meaning of video_count vs new_video_count, which an agent cannot derive from 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?
Front-loads purpose, then interpretation rules, then return shape — a sensible order. The final sentence enumerating returned fields partly duplicates the output schema, making it slightly longer than necessary.
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?
For a zero-parameter read tool with an output schema and read-only annotations, everything an agent needs is present: what a test is, how results are ordered, how to resolve 'the last test', and what fields appear. No material gaps remain.
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?
Zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly does not invent parameter details.
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?
States a specific verb and resource ('List the authenticated user's Userbrain tests') and then defines what a test actually is (unmoderated usability study with URL, language, tasks, tester videos). This domain grounding lets an agent distinguish list_tests from get_test/get_videos without opening any schema.
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?
Gives clear interpretive guidance for ambiguous user phrasing: 'the last test' / 'the latest test' maps to the first item in this list, which is valuable routing context. It does not, however, explicitly name siblings like get_test for fetching a single test by id, leaving that inference to the agent.
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.
get_insights2 fields changedOutput schema / properties / insights / properties / insights / items / properties / clips / items / properties / tester / properties / name / descriptionAdded value: +"Tester display name"Output schema / properties / insights / properties / insights / items / properties / notes / items / properties / tester / properties / name / descriptionAdded value: +"Tester display name"get_test1 field changedOutput schema / properties / test / properties / status / descriptionPrevious value: -"Test lifecycle status."New value: +"Test lifecycle status: `draft` (A test with neither an active invitation link, a running video/tester order, nor any testing results); `completed` (all running tester orders are completed and the invitation link is not active); `running` (either the invitation link is active or an order is not completed yet); `paused` (legacy status that is not used anymore)."get_videos8 fields changedOutput schema / properties / videos / items / properties / clips / items / properties / tester / properties / name / descriptionAdded value: +"Tester display name"Output schema / properties / videos / items / properties / responses / items / properties / response / anyOfPrevious value: -[
- {
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "choice": {
- "anyOf": [
- {
- "type": "number"
- },
- {
- "items": {
- "type": "number"
- },
- "type": "array"
- }
- ],
- "description": "Selected option index/indices (0-based)."
- },
- "completed": {
- "type": "boolean"
- },
- "rating": {
- "type": "number"
- },
- "response": {
- "type": "string"
- },
- "skipped": {
- "type": "boolean"
- }
- },
- "type": "object"
- },
- {
- "description": "Empty array [] — no answer for this step.",
- "items": {},
- "maxItems": 0,
- "type": "array"
- }
- ]
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "choice": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ }
+ ],
+ "description": "Selected option index/indices (0-based)."
+ },
+ "completed": {
+ "type": "boolean"
+ },
+ "rating": {
+ "type": "number"
+ },
+ "response": {
+ "type": "string"
+ },
+ "skipped": {
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ {
+ "description": "Empty array [] — no answer for this step.",
+ "items": {},
+ "maxItems": 0,
+ "type": "array"
+ }
+]Output schema / properties / videos / items / properties / responses / items / properties / response / descriptionPrevious value: -"The tester's answer for the step. An object with the key(s) for that step type (whitelisted in Tester\\ApiController: completed/skipped booleans, choice int or int[], rating int, response string), or an empty array [] when there is no answer."New value: +"The tester's answer for the step"Output schema / properties / videos / items / properties / tester / properties / name / descriptionAdded value: +"Tester display name"Output schema / properties / videos / items / properties / transcript / anyOfRemoved value: -[
- {
- "items": {
- "additionalProperties": false,
- "properties": {
- "end": {
- "description": "Segment end in seconds.",
- "type": "number"
- },
- "start": {
- "description": "Segment start in seconds.",
- "type": "number"
- },
- "transcript": {
- "type": "string"
- }
- },
- "required": [
- "end",
- "start",
- "transcript"
- ],
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]Output schema / properties / videos / items / properties / transcript / descriptionPrevious value: -"Full transcript as an array of time-coded segments. Present only when AI features are enabled and a transcript exists.\n"New value: +"Full transcript as an array of time-coded segments (seconds). Key present only when AI features are enabled and a transcript exists.\n"Output schema / properties / videos / items / properties / transcript / itemsAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "end": {
+ "description": "Segment end in seconds.",
+ "type": "number"
+ },
+ "start": {
+ "description": "Segment start in seconds.",
+ "type": "number"
+ },
+ "transcript": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "end",
+ "start",
+ "transcript"
+ ],
+ "type": "object"
+}Output schema / properties / videos / items / properties / transcript / typeAdded value: +"array"list_tests1 field changedOutput schema / properties / tests / items / properties / status / descriptionPrevious value: -"Test lifecycle status."New value: +"Test lifecycle status: `draft` (A test with neither an active invitation link, a running video/tester order, nor any testing results); `completed` (all running tester orders are completed and the invitation link is not active); `running` (either the invitation link is active or an order is not completed yet); `paused` (legacy status that is not used anymore)."get_insightsget_tasksget_testget_videoslist_tests
Add one secure layer between your agents and this server.