Formhaus Cloud

Form response statistics

form_stats

Read-only

Reports on the responses of one form, such as answer counts per option, average ratings, the NPS or responses per week; it counts every response in the range and returns no answer text. get_submissions reads individual answers. Requires an account key (fh_live_...) of the form's account or the agent key (fh_agent_...) that created the form. since (inclusive, default: when the form was created) and until (exclusive, default: now) take RFC 3339 or a UTC date. interval is day (default), week (weeks start on Monday) or month; buckets are in UTC and a range of more than 366 buckets answers invalid_range: narrow it or use a longer interval.

Returns form_id, since, until, interval, total (responses in the range), series (start and count of each bucket, oldest first, empty buckets included) and fields: one entry per question of the current form version with key, label, type, kind, answered and skipped (total minus answered). By kind:

choice (select, radio, multiselect, checkbox, switch): options (value, label, count; a multiselect answer counts once per option) and other (answers whose value is not an option of the current version). matrix is the key of the matrix section of a matrix row.
scale (scale and rating): points (value, label, count), mean and median. Answers outside the range count as skipped.
nps (a scale from 0 to 10): the same as scale plus nps: score from -100 to 100, promoters (9 and 10), passives (7 and 8), detractors (0 to 6).
number: numbers with count (numeric answers), min, max and mean.
text (text, email, phone, textarea, date, datetime, time, file, hidden, group): answered and skipped only. mean and median are absent when nothing was answered. timing is present when responses in the range were timed by the hosted page or the embed: responses (timed responses, the latest 2000 at most), total_median_ms and questions (key, label, responses, median_ms, p75_ms of the time each question was focused). Calls share the rate limit of submission searches and exports.

Input Schema

Name	Required	Description
`since`	No	Only responses at or after this time: RFC 3339 or a UTC date (2026-10-01). Default: when the form was created.
`until`	No	Only responses before this time: RFC 3339, or a UTC date to include that whole day. Default: now.
`form_id`	Yes	The 10-character form_id returned by publish_form or list_forms, such as "abcDEF1234".
`interval`	No	Bucket size of series in UTC: day (default), week (from Monday) or month. At most 366 buckets.

Output Schema

Name	Required	Description	Default
`since`	Yes
`steps`	No
`total`	Yes
`until`	Yes
`fields`	Yes
`series`	Yes
`timing`	No
`form_id`	Yes
`interval`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 21, 2026

addedOutput schema / properties / timing

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "questions": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "median_ms": {
+            "type": "integer"
+          },
+          "p75_ms": {
+            "type": "integer"
+          },
+          "responses": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "key",
+          "label",
+          "responses",
+          "median_ms",
+          "p75_ms"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "responses": {
+      "type": "integer"
+    },
+    "total_median_ms": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "responses",
+    "total_median_ms",
+    "questions"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

Changed2 schema fields changedOct 21, 2026

addedOutput schema / properties / fields / items / properties / matrix_title
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / steps

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "reached": {
+        "type": "integer"
+      },
+      "title": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "title",
+      "reached"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

AddedOct 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations establish read-only safety, but the description adds crucial behavior beyond that: it returns no answer text, requires a specific key, defaults date bounds, enforces bucket limits with the invalid_range error, and shares submission-search rate limits. This gives an agent enough context to anticipate output scope and failure modes.

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?

The purpose and alternative routing are front-loaded, and the structure is clear. It is longer than necessary because an output schema exists and much of the return-value enumeration repeats structured data, though the detail is not disorganized.

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 a complex stats endpoint, the description covers auth, date defaults, interval constraints, rate limits, and return shape. Even though an output schema exists, the description is complete enough for an agent to call the tool correctly without opening additional docs.

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 schema already documents all four parameters. The description nonetheless adds useful meaning, especially the invalid_range failure when more than 366 buckets are requested and the inclusive/exclusive date semantics in one place, so it exceeds the baseline 3.

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?

The first sentence states a specific verb and resource: reports on responses of one form, with concrete examples such as answer counts, average ratings, NPS, and responses per week. It explicitly contrasts with get_submissions ('reads individual answers'), letting an agent distinguish aggregate statistics from individual answer retrieval.

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?

It names the relevant alternative, get_submissions, and states its different role, so the agent knows when to choose form_stats versus reading raw answers. It also gives prerequisites (account/agent key) and constraints (date range, interval, invalid_range) that govern correct use.

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

All Formhaus Cloud tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?