TheySaid

Propose usability test

propose_usability_test

Plans an AI usability test on a public prototype URL or an uploaded design (uploadId) without launching it: no AI testers run and nothing is spent. It creates a new draft test; re-testing an existing project is done with relaunch_usability_test instead. Plans are better with context from the user: the decision the test informs, the target users (titles, industry, company size, worldview, motivation, familiarity with the product) and the key flows. These map to learningGoals, audienceSpec and tasks. The default plan is short: 2 tasks and 3 questions (a ~15-20 minute run); depth: "deep" plans 5 tasks and 6 questions. Questions are open_ended, multiple_choice (options), rating (scale: min-max of 1-3, 1-5, 1-7 or 0-10 plus end labels) or ranking (options are the items). Sends progress notifications while planning when the client passes a progressToken. Returns a proposalId, personas, tasks, questions, learning goals, an instant design scan and a reviewMessage for the user. Edits go through revise_usability_test, and the test starts only through launch_usability_test once the user approves the plan. Without a prototype source, or with a URL behind a login, the response lists the options (a public URL, or a design snapshot via prepare_design_snapshot). Fields you set (tasks, questions, audienceSpec, project, learningGoals) are applied verbatim and echoed back; omitted fields get AI defaults. Use audienceSpec (exact) or audience (free text); with personaIds, only audienceSpec.numTesters applies. voice.voiceIds takes ElevenLabs voice IDs from search_ai_tester_voices, not voice names.

Input Schema

Name	Required	Description	Default
`depth`	No
`tasks`	No
`intent`	No
`project`	No
`audience`	No
`uploadId`	No
`questions`	No
`personaIds`	No
`audienceSpec`	No
`prototypeUrl`	No
`learningGoals`	No
`prototypeImage`	No

Output Schema

Name	Required	Description
`depth`	No
`intents`	No	Intent presets available for a re-propose.
`audience`	No	The resolved audience envelope echoed back so the caller can report exactly what was applied.
`messages`	No	Extra messages shown after the prototype opens, before the first task.
`personas`	No	Personas this proposal will run.
`taskPlan`	No
`quickScan`	No	Instant L1 design scan; null when nothing surfaced.
`numTesters`	No	Number of AI testers this proposal will deploy.
`proposalId`	No	Cache handle passed to launch_usability_test.
`projectMeta`	No	Resolved project copy/metadata persisted at launch.
`taskDetails`	No	Fully-resolved tasks with per-task success/feedback toggles.
`welcomeText`	No	The first message testers see (introText, else generated or default).
`learningGoals`	No	Analytics objectives this test will be measured against.
`reviewMessage`	No	User-facing message: this is a reviewable plan that has NOT launched.
`personaGallery`	No	Other gallery personas the caller can swap in.
`questionDetails`	No	Fully-resolved follow-up questions with depth/type/options.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 3, 2026

changedInput schema / properties / questions / anyOf

Previous value: -[
-  {
-    "items": {
-      "properties": {
-        "followUps": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "options": {
-          "anyOf": [
-            {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "required": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "text": {
-          "type": "string"
-        },
-        "type": {
-          "anyOf": [
-            {
-              "enum": [
-                "open_ended",
-                "multiple_choice"
-              ],
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        }
-      },
-      "required": [
-        "text"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "followUps": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "options": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "required": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "scale": {
+          "anyOf": [
+            {
+              "properties": {
+                "highLabel": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "lowLabel": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "max": {
+                  "type": "number"
+                },
+                "min": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "min",
+                "max"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "text": {
+          "type": "string"
+        },
+        "type": {
+          "anyOf": [
+            {
+              "enum": [
+                "open_ended",
+                "multiple_choice",
+                "rating",
+                "ranking"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "text"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / messages

Added value: +{
+  "description": "Extra messages shown after the prototype opens, before the first task.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / questionDetails / items / properties / options / description
```
Added value: +"Multiple-choice options or ranking items."
```

addedOutput schema / properties / questionDetails / items / properties / scale

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "highLabel": {
+          "type": "string"
+        },
+        "lowLabel": {
+          "type": "string"
+        },
+        "max": {
+          "type": "number"
+        },
+        "min": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Rating questions only: the numeric scale and its end labels."
+}

changedOutput schema / properties / questionDetails / items / properties / type / enum

Previous value: -[
-  "open_ended",
-  "multiple_choice"
-]New value: +[
+  "open_ended",
+  "multiple_choice",
+  "rating",
+  "ranking"
+]

addedOutput schema / properties / welcomeText

Added value: +{
+  "description": "The first message testers see (introText, else generated or default).",
+  "type": "string"
+}

First observedOct 16, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Beyond the annotations it discloses genuinely behavioral facts: nothing runs and nothing is spent, a draft is created, supplied fields are applied verbatim and echoed back, omitted fields get AI defaults, and progress notifications fire only when a progressToken is passed. It also states the failure behavior for missing or auth-walled prototypes. It loses a point for restating the return payload (proposalId, personas, tasks, questions) that the output schema already provides.

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?

Dense but front-loaded: the no-op planning guarantee and the sibling routing come first, then plan composition, then return shape, then error paths. Long, but the length is mostly earned by the undocumented schema; the return-value recap is the one block that could be cut.

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

Completeness4/5

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

For a 12-parameter, zero-schema-description planning tool with an output schema and annotations, this is close to complete: it covers defaults, depth semantics, question shapes, audience precedence, preview-vs-launch boundaries and the missing-prototype failure mode. The gaps are a few secondary parameters (intent, project, prototypeImage) that an agent must guess at.

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?

With 0% schema description coverage the description carries the load, and it delivers real meaning for the hard fields: the default is 2 tasks/3 questions, depth 'deep' means 5 tasks and 6 questions, question types and their option/scale shapes, and the audienceSpec-vs-audience-vs-personaIds precedence rule including the voiceIds source. It leaves intent, project, prototypeImage and the task successEnabled/feedbackEnabled flags undocumented.

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?

Opens with a specific verb+resource+scope: 'Plans an AI usability test on a public prototype URL or an uploaded design (uploadId) without launching it'. It immediately distinguishes itself from relaunch_usability_test, revise_usability_test and launch_usability_test by name, so an agent can route correctly 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 names the alternatives and the conditions that select them: re-testing an existing project goes to relaunch_usability_test, edits go to revise_usability_test, and launching requires launch_usability_test after user approval. It also states the fallback when the prototype source is missing or login-gated (public URL or prepare_design_snapshot).

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

All TheySaid 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.

Resources

Need Help?