Skip to main content
Glama

List form submissions

list_submissions
Read-onlyIdempotent

List what visitors submitted through a site's forms (the Inbox), newest first, with every answer they gave — message, budget, custom questions — alongside name, email and phone. Use it to read, triage, summarise or judge leads ("which look genuine?", "what is this person asking for?"). Filter by Inbox status, form slug, free-text search on email/name, a submitted-at window, or arrival source. Test-mode submissions are left out unless include_test is true. PERSONAL DATA: answer the owner's question with it; do not copy it into site content or anywhere the user did not ask for. Paginated — compare total with limit/offset before concluding you have seen everyone.

Input Schema

NameRequiredDescriptionDefault
formNoOnly submissions from this form, by its slug (see list_forms)
limitNoPage size, default 25, max 100
offsetNoRows to skip, for paging
searchNoCase-insensitive match on the submitter's email or name
sourceNo"web" for the site's own forms, "agent" for enquiries sent by AI agents
statusNoOnly submissions in this Inbox status
site_idYesThe site, from list_sites
to_dateNoSubmitted on or before this ISO date/time
categoryNoOnly this submission category, when the site defines categories
from_dateNoSubmitted on or after this ISO date/time, e.g. "2026-09-01"
user_goalNoOptional: the user's goal behind this call, in one short sentence of plain words (e.g. "add a page so customers can book tables"). No names, emails or other personal details.
include_testNoInclude submissions made with the editor's test mode (default false)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / user_goal
      Added value: +{
      +  "description": "Optional: the user's goal behind this call, in one short sentence of plain words (e.g. \"add a page so customers can book tables\"). No names, emails or other personal details.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only cover the safety profile (readOnly, idempotent); the description adds genuinely new behaviour: newest-first ordering, the fact that test-mode rows are hidden unless include_test is true, the personal-data handling constraint, and the pagination caveat about comparing `total` with `limit`/`offset` before concluding completeness. It also sketches the returned fields despite there being no output schema.

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-loaded with the purpose and contents, then usage, then filters, then caveats — a sensible information hierarchy. The PERSONAL DATA sentence is a policy instruction that consumes real space, but it does earn its place for a personal-data-returning tool; the paragraph is dense rather than padded.

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?

With no output schema and 12 parameters, the description carries real burden and mostly meets it: return contents, sort order, test-mode default, and pagination semantics are all stated. Gaps are modest — the `category` filter and the `user_goal` field go unmentioned, and there is no note on auth or empty-result behaviour.

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 description coverage is 100%, so baseline is 3. The description groups the filter parameters ('status', `form` slug, `search` on email/name, submitted-at window, `source`) which helps an agent see the filter surface at a glance, but it largely restates the schema and says nothing about `category` or how `limit`/`offset` combine with `total` beyond the pagination warning.

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 ('List what visitors submitted through a site's forms') and adds scope details that matter: the Inbox, newest-first ordering, and full answer payloads (message, budget, custom questions) plus contact fields. An agent can distinguish this from list_forms (which presumably lists the forms themselves) and from export_submissions or delete_submissions without opening a schema.

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 concrete usage intents ('read, triage, summarise or judge leads') with real user-question examples, which tells the agent the right situations to reach for it. It does not name alternative siblings (export_submissions for bulk extraction, update_submission_status for triage actions, list_forms for discovery), so the negative case is left implicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources