Formaly

List forms

Use this when the user wants to see their existing forms or surveys, or asks 'what forms do I have'. Returns a paginated list with response counts. Filter by status (draft, active, closed).

Get a form

Use this when the user references a specific form by id and you need its full details plus its question schema. Returns the form record and a machine-readable field list you can render or reason over.

Get a form's schema

Use this when you need only the machine-readable structure of a form (fields, types, options, validation) to render it in another channel or build answers - without the full record. This is the canonical 'how do I fill out this form' shape.

Get form responses

Use this when the user wants to read the actual answers/submissions to a form (e.g. 'show me what people said'). Returns paginated responses with structured answer data, most recent first.

Get form analytics

Use this when the user asks how a form/survey is performing - completion rate, average time, drop-off by question, device and traffic-source breakdown. Returns aggregated stats, not individual answers.

Get credit balance

Use this when the user asks how many credits they have left, or before an operation that might cost credits (generating a form costs credits). Returns current balance and lifetime usage.

Create a form

Use this when the user wants to create a new form or survey from a description (e.g. 'make me an NPS survey for churned users'). Generates the questions with AI and saves it. This consumes credits - check get_credits first if unsure. Pass a stable request_id so a retry doesn't create a duplicate form.

Update a form

Use this when the user wants to change a form's metadata - rename it, edit its description, switch its default mode, toggle contact-info collection, or set a custom AI system prompt. To publish or close a form, prefer set_form_status. Pass expected_version (the `version` from get_form) so a concurrent edit is rejected instead of silently overwritten.

Publish, close, or unpublish a form

Use this when the user wants to publish a form so it accepts responses (status 'active'), close it to new responses ('closed'), or move it back to 'draft'. Pass expected_version to guard against concurrent edits.

Delete a form

Use this when the user explicitly asks to permanently delete a form and all of its responses. This cannot be undone - confirm intent with the user before calling. Pass a request_id so a retried call returns success instead of NOT_FOUND after the form is already gone.