TheySaid

Responses search

responses_search

Read-onlyIdempotent

Search/filter individual responses across the whole org or one project. Filters: signal (positive/negative/neutral/mixed), quality (high/medium/low), channel (link/website/email/qr-code/social-media/panel), date window, free-text keyword (matches summary + respondent name/email), a specific contactId, and friction (frictionCategories and/or minFrictionSeverity: responses with a friction moment of that category / at least that severe). Returns each response's insight id, share id + public shareUrl, summary, signal, quality, channel, date, project, and the respondent's name/email when present. Set includeConversation=true to also return each response's full conversation transcript (each turn carries its messageId + questionId, so you can cite a specific message) — use this when EXPORTING responses so the export contains the conversation. In a report run that returns at most 10 responses with only the respondent's turns, each cut to 500 characters. Use for 'negative responses about X', 'responses from ', 'low-quality responses since '.

Input Schema

Name	Required	Description
`limit`	No	Max responses (default 20, max 50).
`since`	No	ISO date lower bound, or null.
`until`	No	ISO date upper bound, or null.
`signal`	No	positive \| negative \| neutral \| mixed, or null.
`channel`	No	link \| website \| email \| qr-code \| social-media \| panel, or null.
`keyword`	No	Case-insensitive match on summary title and respondent name/email, or null.
`quality`	No	high \| medium \| low, or null. Low-quality responses are archived, so pass "low" explicitly to include them — they are excluded from every other filter combination.
`contactId`	No	Limit to one contact (from contact_list), or null.
`projectId`	No	Limit to one project, or null to search the whole organization.
`includeUnset`	No	Only (or also, with audienceGroupIds) responses with no audience group ("not set"), or null.
`audienceGroupIds`	No	Only responses of these audience groups (ids from a response's audienceGroupId), ORed with includeUnset; or null.
`frictionCategories`	No	Only responses quoted in a friction observation of one of these categories, or null.
`includeConversation`	No	When true, each response also includes its full conversation as a `conversation` array of { sender, text } turns (the same transcript response_detail returns, fetched in bulk for all matched responses). Use this when exporting responses so the export contains the conversation.
`minFrictionSeverity`	No	Only responses with a friction moment at least this severe (Mild < Moderate < Severe < Blocking), or null.

Output Schema

Name	Required	Description	Default
`error`	No
`responses`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 3, 2026

removedInput schema / properties / minFrictionImpact

Removed value: -{
-  "anyOf": [
-    {
-      "enum": [
-        "critical",
-        "high",
-        "medium",
-        "low"
-      ],
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Only responses quoted in a friction observation at least this impactful (low < medium < high < critical), or null."
-}

addedInput schema / properties / minFrictionSeverity

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "Mild",
+        "Moderate",
+        "Severe",
+        "Blocking"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Only responses with a friction moment at least this severe (Mild < Moderate < Severe < Blocking), or null."
+}

changedOutput schema / properties / responses / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "channel": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "conversation": {
-          "anyOf": [
-            {
-              "items": {
-                "additionalProperties": false,
-                "properties": {
-                  "messageId": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  },
-                  "questionId": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  },
-                  "sender": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  },
-                  "text": {
-                    "anyOf": [
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  }
-                },
-                "type": "object"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "createdAt": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "email": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "firstName": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "id": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "lastName": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "projectId": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "projectTitle": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "quality": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "shareId": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "signal": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "summaryTitle": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "channel": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "conversation": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "messageId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "questionId": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "sender": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "text": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "email": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "firstName": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "lastName": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "projectId": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "projectTitle": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "quality": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "shareId": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "shareUrl": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "signal": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "summaryTitle": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

Changed2 schema fields changedOct 29, 2026

addedInput schema / properties / audienceGroupIds

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Only responses of these audience groups (ids from a response's audienceGroupId), ORed with includeUnset; or null."
+}

addedInput schema / properties / includeUnset

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Only (or also, with audienceGroupIds) responses with no audience group (\"not set\"), or null."
+}

Changed2 schema fields changedOct 26, 2026

addedInput schema / properties / frictionCategories

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "enum": [
+          "Broken",
+          "Confusing",
+          "Hard to Find",
+          "Too Complex",
+          "Too Slow",
+          "Visually Unappealing",
+          "Low Trust",
+          "Missing / Insufficient",
+          "Interruptive",
+          "Inconsistent",
+          "Inaccessible",
+          "Human / Service Issue",
+          "Price / Value Problem",
+          "Environmental / Situational Constraint"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Only responses quoted in a friction observation of one of these categories, or null."
+}

addedInput schema / properties / minFrictionImpact

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "critical",
+        "high",
+        "medium",
+        "low"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Only responses quoted in a friction observation at least this impactful (low < medium < high < critical), or null."
+}

First observedOct 16, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the bar is lower, yet the description adds real behavioral context: a report run caps output at 10 responses, truncates each turn to 500 characters, and can attach full transcripts. It does not mention pagination or rate/permission constraints, which are the remaining gaps for a 14-parameter search.

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?

Front-loads purpose and filter list, then return shape, then the export caveat — logical order with no filler. The single long paragraph and run-on parentheticals make the 10-response/500-character limit easy to miss, which costs a point.

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

Completeness5/5

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

For a 14-parameter, optional-only search tool it covers the filter surface, output fields, the transcript opt-in, and the report-run truncation rule that would otherwise surprise an agent. Nothing an agent needs to call it correctly is missing, even disregarding the output schema.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds combination semantics the schema lacks — notably that frictionCategories and minFrictionSeverity can be used together ('a friction moment of that category / at least that severe') and that keyword matches summary plus respondent name/email. That goes modestly beyond restating the schema.

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?

States a concrete verb and resource ('Search/filter individual responses') plus its scope (whole org or one project), and enumerates the filter axes. It is clearly distinguishable from sibling tools like recent_responses and response_detail because it is a multi-filter bulk search that returns a summary row per response.

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

Usage Guidelines4/5

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

Gives explicit trigger phrases ('negative responses about X', 'responses from <contact>', 'low-quality responses since <date>') and a clear conditional rule for includeConversation during exports. It never names a sibling alternative (e.g., recent_responses or response_detail) or states when-not to use it, so it falls short of full routing guidance.

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?