TheySaid

Revise usability test

revise_usability_test

Destructive

Edits a usability test. Takes exactly one of proposalId (an unlaunched draft) or projectId (an already-launched test). Draft: plain-language changes and/or structured edits (add or remove tasks, questions and learning goals by index, swap personaIds, set edits.audience). Returns an updated plan under a new proposalId that replaces the previous one; nothing is launched. The number of AI testers changes only through edits.audience.numTesters. Launched test: only the audience can change (edits.audience, edits.personaIds). The change is saved to the project and echoed back as audience, and nothing runs until relaunch_usability_test. Tasks, questions and learning goals of a launched test cannot be edited; a new test is needed for that.

Input Schema

Name	Required	Description	Default
`edits`	No
`changes`	No
`projectId`	No
`proposalId`	No

Output Schema

Name	Required	Description
`depth`	No
`testId`	No	Launched-project variant: the edited project id (unchanged).
`intents`	No	Intent presets available for a re-propose.
`message`	No	Launched-project variant: the change is saved; relaunch to run it.
`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.
`reusedProject`	No	Launched-project variant: confirms no new project was created.
`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 / edits / anyOf

Previous value: -[
-  {
-    "properties": {
-      "addLearningGoals": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "addQuestions": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "addTasks": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "audience": {
-        "anyOf": [
-          {
-            "properties": {
-              "ageMax": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "ageMin": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "biologicalSex": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "companyIndustry": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "companySize": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "knowledgebase": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "motivation": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "numTesters": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "personality": {
-                "anyOf": [
-                  {
-                    "items": {
-                      "properties": {
-                        "dimension": {
-                          "type": "string"
-                        },
-                        "max": {
-                          "type": "number"
-                        },
-                        "min": {
-                          "type": "number"
-                        }
-                      },
-                      "required": [
-                        "dimension",
-                        "min",
-                        "max"
-                      ],
-                      "type": "object"
-                    },
-                    "type": "array"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "titles": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "useProxy": {
-                "anyOf": [
-                  {
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "voice": {
-                "anyOf": [
-                  {
-                    "properties": {
-                      "similarityBoost": {
-                        "anyOf": [
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "speakerBoost": {
-                        "anyOf": [
-                          {
-                            "type": "boolean"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "speed": {
-                        "anyOf": [
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "stability": {
-                        "anyOf": [
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "style": {
-                        "anyOf": [
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "voiceIds": {
-                        "anyOf": [
-                          {
-                            "items": {
-                              "type": "string"
-                            },
-                            "type": "array"
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      }
-                    },
-                    "type": "object"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "worldview": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "personaIds": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "removeLearningGoalIndexes": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "number"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "removeQuestionIndexes": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "number"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "removeTaskIndexes": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "number"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "addLearningGoals": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "addQuestionSpecs": {
+        "anyOf": [
+          {
+            "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"
+          }
+        ]
+      },
+      "addQuestions": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "addTasks": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "audience": {
+        "anyOf": [
+          {
+            "properties": {
+              "ageMax": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "ageMin": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "biologicalSex": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "companyIndustry": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "companySize": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "knowledgebase": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "motivation": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "numTesters": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "personality": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "properties": {
+                        "dimension": {
+                          "type": "string"
+                        },
+                        "max": {
+                          "type": "number"
+                        },
+                        "min": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "dimension",
+                        "min",
+                        "max"
+                      ],
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "titles": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "useProxy": {
+                "anyOf": [
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "voice": {
+                "anyOf": [
+                  {
+                    "properties": {
+                      "similarityBoost": {
+                        "anyOf": [
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "speakerBoost": {
+                        "anyOf": [
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "speed": {
+                        "anyOf": [
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "stability": {
+                        "anyOf": [
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "style": {
+                        "anyOf": [
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "voiceIds": {
+                        "anyOf": [
+                          {
+                            "items": {
+                              "type": "string"
+                            },
+                            "type": "array"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      }
+                    },
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "worldview": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "personaIds": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "removeLearningGoalIndexes": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "number"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "removeQuestionIndexes": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "number"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "removeTaskIndexes": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "number"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "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.7/5.0

Behavior5/5

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

The annotations declare destructiveHint=true and idempotentHint=false, but give no account of what is actually destroyed or replaced. The description fills that gap precisely: a revision returns an updated plan under a NEW proposalId that replaces the previous one, nothing is launched, and for launched tests the change is merely saved to the project and echoed back as `audience` until relaunch_usability_test. It also discloses a non-obvious side constraint — tester count can only change via `edits.audience.numTesters` — which is behavior no structured field conveys.

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 and front-loaded, with the mode-selection rule first and the draft/launched split clearly sequenced; nearly every clause adds a constraint an agent could not infer. There is mild redundancy between "nothing is launched" and "nothing runs until relaunch_usability_test," and the single-paragraph block would scan faster as two mode-labeled segments.

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 four-parameter, high-branching mutation tool with no schema descriptions, the description supplies the decision rules, per-mode editability, side effects and hand-off to relaunch, and an output schema exists so return values need not be spelled out. The remaining gap is the un-described breadth of the nested `edits.audience` object, which the description gestures at rather than enumerates.

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 across four top-level parameters and a deeply nested `edits` object, the description carries the full burden and mostly delivers: it defines proposalId vs projectId, distinguishes free-text `changes` from structured `edits`, and explains index-based add/remove plus personaId swapping. It stops short on parts of the nested surface (e.g. `addQuestionSpecs`, `removeQuestionIndexes`/`removeLearningGoalIndexes` as distinct from the generic "remove ... by index", and the individual `edits.audience` fields), leaving some guessing for anything below `edits.audience.numTesters`.

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 ("Edits a usability test") and immediately splits the operation into two mutually exclusive modes keyed on `proposalId` (unlaunched draft) versus `projectId` (already-launched test). It also names the sibling that actually runs the test (relaunch_usability_test), so an agent can place this tool in the workflow without inspecting schemas.

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?

States the selection rule explicitly ("Takes exactly one of proposalId or projectId"), then gives per-mode capability boundaries: drafts can add/remove tasks, questions and learning goals by index and swap personaIds, while launched tests allow only audience changes. It goes further with a when-not rule — tasks/questions/goals of a launched test cannot be edited and a new test is needed instead — which is exactly the kind of exclusion that prevents wrong calls.

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?