humansurvey-mcp

Create Survey

create_survey

Create a structured survey to collect feedback from a group. Define questions with types like single choice, multi choice, text, scale, or matrix. Get a shareable URL to collect responses and a survey ID to retrieve results later.

Instructions

Use this when an agent task involves collecting structured feedback or data from a group of people. Common cases: post-event attendee feedback, product satisfaction after a launch, team health checks, customer ratings after support resolution. The schema parameter is fully typed — follow the field types rather than guessing. Returns a survey_url to share with respondents and a survey_id to pass to get_results later. The survey accepts responses immediately and stays open until you close it or it expires. Embedding: append "?embed=1" to the returned survey_url to render inside an on any host site (onboarding/lead-capture flows). The embedded form posts events to window.parent with source: "humansurvey" — type "loaded", "resize" (with height), and "submitted" (with responseId and answers). See https://www.humansurvey.co/llms.txt for the full embed contract.

Input Schema

TableJSON Schema

Name	Required	Description
`schema`	Yes	Survey definition. Each question is a discriminated union keyed by type: single_choice, multi_choice, text, scale, or matrix. Use the typed fields below — do not send free-form JSON.
`max_responses`	No	Optional. Close the survey automatically after this many responses.
`expires_at`	No	Optional. ISO 8601 datetime — close the survey automatically at this time (e.g. "2026-04-14T00:00:00Z").
`webhook_url`	No	Optional. URL to POST to once when the survey closes. Payload: { survey_id, status: "closed", closed_reason: "manual" \| "max_responses", response_count, closed_at }. Fires when you call close_survey or when max_responses is reached. Does not fire when expires_at elapses.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed5 schema fields changedv0.1.2Apr 26, 2026

removedInput schema / properties / schema / additionalProperties
```
Removed value: -{}
```

changedInput schema / properties / schema / description

Previous value: -"Survey as a JSON schema object: { title: string, sections: [{ questions: [{ type, label, ...}] }] }. Question types: single_choice (needs options), multi_choice (needs options), text, scale (needs min/max, range ≤ 11), matrix (needs rows + columns). Add showIf: { questionId, operator: \"eq\"|\"neq\"|\"contains\"|\"answered\", value } to any question for conditional logic."New value: +"Survey definition. Each question is a discriminated union keyed by type: single_choice, multi_choice, text, scale, or matrix. Use the typed fields below — do not send free-form JSON."

addedInput schema / properties / schema / properties

Added value: +{
+  "description": {
+    "description": "Optional intro text shown on the welcome screen.",
+    "type": "string"
+  },
+  "sections": {
+    "description": "Survey sections, each with questions. Use a single section for simple surveys.",
+    "items": {
+      "properties": {
+        "description": {
+          "description": "Optional section description.",
+          "type": "string"
+        },
+        "questions": {
+          "description": "Questions in this section.",
+          "items": {
+            "oneOf": [
+              {
+                "properties": {
+                  "description": {
+                    "description": "Optional helper text shown under the question label.",
+                    "type": "string"
+                  },
+                  "label": {
+                    "description": "Question text shown to the respondent.",
+                    "type": "string"
+                  },
+                  "options": {
+                    "description": "Options the respondent chooses exactly one of.",
+                    "items": {
+                      "properties": {
+                        "hasTextInput": {
+                          "description": "Set true for an \"Other: ___\" option that lets the respondent type a free-text value.",
+                          "type": "boolean"
+                        },
+                        "label": {
+                          "description": "Option text shown to the respondent.",
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "label"
+                      ],
+                      "type": "object"
+                    },
+                    "minItems": 1,
+                    "type": "array"
+                  },
+                  "required": {
+                    "description": "Whether an answer is required. Defaults to false.",
+                    "type": "boolean"
+                  },
+                  "showIf": {
+                    "description": "Only show this question if the condition on an earlier question is met.",
+                    "properties": {
+                      "operator": {
+                        "description": "eq = referenced answer equals value; neq = not equal; contains = multi_choice selection includes value; answered = respondent gave any answer.",
+                        "enum": [
+                          "eq",
+                          "neq",
+                          "contains",
+                          "answered"
+                        ],
+                        "type": "string"
+                      },
+                      "questionId": {
+                        "description": "ID of the earlier question to check. IDs are assigned in order of appearance as q_0, q_1, q_2, ... across all sections. Must reference a question before the one where showIf is set.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Option ID (opt_0, opt_1, ...) for eq/neq/contains — numbered per-question in option order. Omit for the answered operator.",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "questionId",
+                      "operator"
+                    ],
+                    "type": "object"
+                  },
+                  "type": {
+                    "const": "single_choice",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "type",
+                  "label",
+                  "options"
+                ],
+                "type": "object"
+              },
+              {
+                "properties": {
+                  "description": {
+                    "description": "Optional helper text shown under the question label.",
+                    "type": "string"
+                  },
+                  "label": {
+                    "description": "Question text shown to the respondent.",
+                    "type": "string"
+                  },
+                  "options": {
+                    "description": "Options the respondent can pick one or more of.",
+                    "items": {
+                      "properties": {
+                        "hasTextInput": {
+                          "description": "Set true for an \"Other: ___\" option that lets the respondent type a free-text value.",
+                          "type": "boolean"
+                        },
+                        "label": {
+                          "description": "Option text shown to the respondent.",
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "label"
+                      ],
+                      "type": "object"
+                    },
+                    "minItems": 1,
+                    "type": "array"
+                  },
+                  "required": {
+                    "description": "Whether an answer is required. Defaults to false.",
+                    "type": "boolean"
+                  },
+                  "showIf": {
+                    "description": "Only show this question if the condition on an earlier question is met.",
+                    "properties": {
+                      "operator": {
+                        "description": "eq = referenced answer equals value; neq = not equal; contains = multi_choice selection includes value; answered = respondent gave any answer.",
+                        "enum": [
+                          "eq",
+                          "neq",
+                          "contains",
+                          "answered"
+                        ],
+                        "type": "string"
+                      },
+                      "questionId": {
+                        "description": "ID of the earlier question to check. IDs are assigned in order of appearance as q_0, q_1, q_2, ... across all sections. Must reference a question before the one where showIf is set.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Option ID (opt_0, opt_1, ...) for eq/neq/contains — numbered per-question in option order. Omit for the answered operator.",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "questionId",
+                      "operator"
+                    ],
+                    "type": "object"
+                  },
+                  "type": {
+                    "const": "multi_choice",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "type",
+                  "label",
+                  "options"
+                ],
+                "type": "object"
+              },
+              {
+                "properties": {
+                  "description": {
+                    "description": "Optional helper text shown under the question label.",
+                    "type": "string"
+                  },
+                  "label": {
+                    "description": "Question text shown to the respondent.",
+                    "type": "string"
+                  },
+                  "required": {
+                    "description": "Whether an answer is required. Defaults to false.",
+                    "type": "boolean"
+                  },
+                  "showIf": {
+                    "description": "Only show this question if the condition on an earlier question is met.",
+                    "properties": {
+                      "operator": {
+                        "description": "eq = referenced answer equals value; neq = not equal; contains = multi_choice selection includes value; answered = respondent gave any answer.",
+                        "enum": [
+                          "eq",
+                          "neq",
+                          "contains",
+                          "answered"
+                        ],
+                        "type": "string"
+                      },
+                      "questionId": {
+                        "description": "ID of the earlier question to check. IDs are assigned in order of appearance as q_0, q_1, q_2, ... across all sections. Must reference a question before the one where showIf is set.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Option ID (opt_0, opt_1, ...) for eq/neq/contains — numbered per-question in option order. Omit for the answered operator.",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "questionId",
+                      "operator"
+                    ],
+                    "type": "object"
+                  },
+                  "type": {
+                    "const": "text",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "type",
+                  "label"
+                ],
+                "type": "object"
+              },
+              {
+                "properties": {
+                  "description": {
+                    "description": "Optional helper text shown under the question label.",
+                    "type": "string"
+                  },
+                  "label": {
+                    "description": "Question text shown to the respondent.",
+                    "type": "string"
+                  },
+                  "max": {
+                    "description": "Highest scale value. The range (max - min + 1) must be ≤ 11.",
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "maxLabel": {
+                    "description": "Label shown at the max end, e.g. \"Very likely\".",
+                    "type": "string"
+                  },
+                  "min": {
+                    "description": "Lowest scale value (usually 0 or 1).",
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "minLabel": {
+                    "description": "Label shown at the min end, e.g. \"Not likely\".",
+                    "type": "string"
+                  },
+                  "required": {
+                    "description": "Whether an answer is required. Defaults to false.",
+                    "type": "boolean"
+                  },
+                  "showIf": {
+                    "description": "Only show this question if the condition on an earlier question is met.",
+                    "properties": {
+                      "operator": {
+                        "description": "eq = referenced answer equals value; neq = not equal; contains = multi_choice selection includes value; answered = respondent gave any answer.",
+                        "enum": [
+                          "eq",
+                          "neq",
+                          "contains",
+                          "answered"
+                        ],
+                        "type": "string"
+                      },
+                      "questionId": {
+                        "description": "ID of the earlier question to check. IDs are assigned in order of appearance as q_0, q_1, q_2, ... across all sections. Must reference a question before the one where showIf is set.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Option ID (opt_0, opt_1, ...) for eq/neq/contains — numbered per-question in option order. Omit for the answered operator.",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "questionId",
+                      "operator"
+                    ],
+                    "type": "object"
+                  },
+                  "type": {
+                    "const": "scale",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "type",
+                  "label",
+                  "min",
+                  "max"
+                ],
+                "type": "object"
+              },
+              {
+                "properties": {
+                  "columns": {
+                    "description": "Columns of the matrix — each column defines the options used for every row.",
+                    "items": {
+                      "properties": {
+                        "label": {
+                          "description": "Column label.",
+                          "type": "string"
+                        },
+                        "options": {
+                          "description": "Options shown in each cell of this column. Every row uses the same column options.",
+                          "items": {
+                            "properties": {
+                              "hasTextInput": {
+                                "description": "Set true for an \"Other: ___\" option that lets the respondent type a free-text value.",
+                                "type": "boolean"
+                              },
+                              "label": {
+                                "description": "Option text shown to the respondent.",
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "label"
+                            ],
+                            "type": "object"
+                          },
+                          "minItems": 1,
+                          "type": "array"
+                        }
+                      },
+                      "required": [
+                        "label",
+                        "options"
+                      ],
+                      "type": "object"
+                    },
+                    "minItems": 1,
+                    "type": "array"
+                  },
+                  "description": {
+                    "description": "Optional helper text shown under the question label.",
+                    "type": "string"
+                  },
+                  "label": {
+                    "description": "Question text shown to the respondent.",
+                    "type": "string"
+                  },
+                  "required": {
+                    "description": "Whether an answer is required. Defaults to false.",
+                    "type": "boolean"
+                  },
+                  "rows": {
+                    "description": "Rows of the matrix — usually items or criteria being evaluated.",
+                    "items": {
+                      "properties": {
+                        "label": {
+                          "description": "Row label — usually an item or criterion being evaluated.",
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "label"
+                      ],
+                      "type": "object"
+                    },
+                    "minItems": 1,
+                    "type": "array"
+                  },
+                  "showIf": {
+                    "description": "Only show this question if the condition on an earlier question is met.",
+                    "properties": {
+                      "operator": {
+                        "description": "eq = referenced answer equals value; neq = not equal; contains = multi_choice selection includes value; answered = respondent gave any answer.",
+                        "enum": [
+                          "eq",
+                          "neq",
+                          "contains",
+                          "answered"
+                        ],
+                        "type": "string"
+                      },
+                      "questionId": {
+                        "description": "ID of the earlier question to check. IDs are assigned in order of appearance as q_0, q_1, q_2, ... across all sections. Must reference a question before the one where showIf is set.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Option ID (opt_0, opt_1, ...) for eq/neq/contains — numbered per-question in option order. Omit for the answered operator.",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "questionId",
+                      "operator"
+                    ],
+                    "type": "object"
+                  },
+                  "type": {
+                    "const": "matrix",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "type",
+                  "label",
+                  "rows",
+                  "columns"
+                ],
+                "type": "object"
+              }
+            ]
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "title": {
+          "description": "Optional section heading.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "questions"
+      ],
+      "type": "object"
+    },
+    "minItems": 1,
+    "type": "array"
+  },
+  "title": {
+    "description": "Survey title shown to respondents on the welcome screen.",
+    "type": "string"
+  }
+}

removedInput schema / properties / schema / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
addedInput schema / properties / schema / required
```
Added value: +[
+  "title",
+  "sections"
+]
```

First observedv0.1.0Apr 8, 2026

TDQS

A4.4/5.0

Behavior5/5

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

No annotations provided, so description carries full burden. Discloses that surveys accept responses immediately, remain open until closed or expired, and explains embed behavior (?embed=1) with window.parent events. Also notes webhook limitations (does not fire on expiration). This goes beyond basic expectations for a creation tool.

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?

Well-structured with clear front-loading: 'Use this when...' followed by examples, then schema guidance, then return values, then embed details. Each sentence serves a purpose. Slightly lengthy but not redundant; could be tightened without losing value.

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?

Given no output schema, the description fully explains return values (survey_url, survey_id) and how to use them. Covers lifecycle (immediate acceptance, expiration, closing), embed functionality, and webhook behavior. This provides a complete mental model for the agent to invoke the tool correctly.

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 100% with detailed descriptions on each field, including nested objects and conditional logic (showIf). The description adds minor value: advises to follow field types and mentions returns (survey_url, survey_id). But the schema already explains parameters thoroughly, so the description adds little beyond baseline.

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?

Clearly states the tool's purpose: creating surveys for collecting structured feedback from groups. Provides specific examples like post-event feedback, product satisfaction, team health checks. The verb 'create' and resource 'survey' are unambiguous, and the description distinguishes it from sibling tools (close_survey, etc.) through context.

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?

Explicitly says when to use: 'when an agent task involves collecting structured feedback or data from a group of people.' Lists common use cases. However, it doesn't explicitly mention when not to use this tool or name alternatives (like using get_results for retrieving responses). The guidance is strong but lacks exclusions.

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

Install Server

Other Tools

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunsiyuan/human-survey'

If you have feedback or need assistance with the MCP directory API, please join our Discord server