FormHug

View saved version →

---
name: formhug-analyze-responses
description: Analyze FormHug submissions and survey responses by filtering entries, summarizing answers, comparing segments, identifying patterns, and producing concise response reports. Use when the user asks questions about collected FormHug entries, respondents, ratings, choices, trends, or open-text feedback. Do not use to modify or submit entries.
---

# Analyze FormHug responses

Produce a traceable analysis whose scope and completeness are clear.

## Workflow

1. Resolve the target and its field definitions through the correct ownership path:
   - For a form the user owns, use `list_forms` if needed, then `get_form` to map field and choice api_codes to human-readable labels.
   - For a form the user submitted to but does not own, use `list_participated_forms`, then `get_published_form` for its public field definitions. Private fields are unavailable on this path.
   - When discovery does not find the target on the first page, follow `next_cursor` until it is found or the list is exhausted. Prefer the `list_forms` name filter for owned forms when a name is known.
2. Restate the analytical question in operational terms: population, date range, segments, metrics, and whether the user needs all matching entries or a sample.
3. Read `formhug://entries-filter` before constructing filters. If direct resource access is unavailable, call `read_reference` with the same URI. Remember that all filter conditions are ANDed, choice filters usually use choice api_codes, and nested fields have special reference syntax.
   - To implement OR logic, run separate paginated queries for each branch, merge the results, and deduplicate them by `serial_number`. Track completeness for every branch rather than treating a partial union as complete.
4. Fetch entries with `list_entries` for an owned form. Use `list_my_entries` only for the authenticated user's own submissions to a participated form; never imply that it returns other respondents' entries.
5. Handle pagination deliberately:
   - Use a limit up to 100 and pass each `next_cursor` into the next call.
   - Continue until `next_cursor` is null when the user needs a complete result.
   - If a complete pull is impractical, analyze a clearly identified sample and state its size and selection method.
   - Use `pagination.total` as the matching count, not as proof that every matching record was fetched.
6. Normalize values with the form definition:
   - Translate choice api_codes back to labels.
   - Distinguish missing values from numeric zero, false, and an intentionally empty selection.
   - Count every selected option for multi-select fields.
   - Interpret dates in the form's timezone and state the reporting period explicitly.
   - Treat free-text themes as qualitative coding; show representative paraphrases rather than exposing unnecessary raw text.
7. Check data quality before drawing conclusions. Report missingness, small groups, inconsistent field usage, duplicate-looking submissions, unsupported comparisons, and any incomplete pagination.
8. Present the answer in this order: direct answer, supporting metrics, notable segments or themes, data-quality caveats, and the analysis scope. Include the FormHug entries URL for an owned form when the user may want to inspect records or built-in reports; do not imply that a participant can access the owner's entries page.

## Privacy and safety

- If FormHug tools are unavailable, pause and ask the user to connect the FormHug app. On an authentication or authorization error, ask the user to reconnect or reauthorize rather than repeatedly retrying. Never fabricate inaccessible entries or analysis results.
- Minimize personal data. Aggregate names, emails, phone numbers, addresses, attachment URLs, and other identifiers unless the user explicitly needs individual records for an authorized purpose.
- Do not reproduce access passwords, credentials, payment-card data, government identifiers, health information, or pr

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: formhug-create-form
description: Create complete FormHug registration forms, application forms, surveys, contact forms, order forms, lead-capture forms, and other unscored forms from a user brief. Use when the user asks to build, generate, or set up a new FormHug form. Do not use for scored quizzes or assessments; use formhug-create-quiz instead.
---

# Create a FormHug form

Turn the user's brief into a usable form, not merely a call to `create_form`.

## Workflow

1. Extract the form's purpose, respondents, requested language, required information, and desired post-submission outcome from the prompt. Ask only for missing information that would materially change the form; otherwise make conservative defaults and state them briefly.
2. Use `list_folders` only when the user requests a folder or an existing organization scheme matters. Never invent folder tokens.
3. Read `formhug://field-types` before composing fields. Follow any linked per-type resource for an advanced field. If direct resource access is unavailable, use `read_reference` with the same URI.
4. Design the shortest field sequence that fulfills the purpose:
   - Put easy, low-friction questions first and sensitive or open-ended questions later.
   - Mark a field required only when the workflow truly needs it.
   - Use the narrowest valid field type instead of approximating everything with text fields.
   - Keep choice labels parallel and unambiguous. Pass choices as objects such as `{ "label": "Option" }`, never as strings.
   - Use `description` fields for necessary instructions; avoid decorative copy that lengthens the form.
5. Call `create_form` once with the complete initial structure. Do not pass `api_code` on new fields. Provide `header_image` as one or two concrete English keywords. Default to `classic`; use `card` only when the user explicitly requests a conversational, one-question-at-a-time flow.
   - Once `create_form` returns a form token, retain it for every remaining step. If a later call fails or its outcome is uncertain, inspect that form and retry only the failed step; never create a replacement form automatically.
6. Configure only the behavior supported by the brief:
   - Use `update_form_settings` for locale, timezone, thank-you message or redirect, availability, access control, and submission options. It is a partial merge: omitted keys remain unchanged, while explicit `null` clears a value.
   - After creation, use `get_form` to obtain field and choice api_codes before defining conditional logic. Read `formhug://field-rules`, then use `update_field_rules` with the full desired list for every rule kind being changed.
   - Read `formhug://themes` before using `update_form_theme`. Do not add theme work when the user only asked for form structure.
7. Verify the saved result with `preview_form` or `get_form`. Check that every requested field exists, required flags are intentional, choices are complete, the locale is correct, and conditional-rule targets occur after their triggers.
8. Report the form name, a compact field summary, assumptions made, and the most relevant FormHug URLs. Always include the public form URL after creation; include edit or share URLs when they are useful next steps.

## Guardrails

- If FormHug tools are unavailable, pause and ask the user to connect the FormHug app. On an authentication or authorization error, ask the user to reconnect or reauthorize rather than repeatedly retrying.
- If direct access to any `formhug://` resource is unavailable, call `read_reference` with the same URI.
- If a tool returns a validation error, correct the payload from that error and the relevant MCP resource. On a network error or uncertain write result, read the current form state before retrying. Never invent a form token, URL, or successful result.
- Never delete or overwrite an existing form while creating a new one.
- Avoid requesting credentials, government identifiers, health data, payment-card data, or other sensitive info

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: formhug-create-quiz
description: Create, edit, audit, and improve scored FormHug quizzes and assessments with questions, answer keys, explanations, choice scores, result ranges, and rich-text score-based feedback. Use for exams, trivia, knowledge tests, evaluations, personality tests, or any existing FormHug form change involving scoring, answers, score ranges, or result reports. Do not use for ordinary unscored forms.
---

# Create or improve a FormHug quiz or assessment

Build a scoring model that is internally valid before creating the form.

## Choose the scene

- Use `quiz` when answers can be correct or incorrect. The only scorable types are `radio`, `checkbox`, `dropdown`, `short_text`, `long_text`, and `number`.
- Use `assessment` when every choice contributes to one meaningful score continuum, such as low-to-high readiness, satisfaction, risk, or maturity. The scorable types are `radio`, `checkbox`, `dropdown`, `likert`, and `rating`.
- Do not pretend that one total score can independently classify several unrelated personality dimensions. If the requested outcome is multidimensional, explain the limitation and ask the user to choose a defensible single continuum or a simpler result model.

## Workflow

1. Establish the subject, audience, language, approximate length, difficulty, result style, and whether explanations are expected. Infer ordinary editorial and presentation details, but clarify ambiguous scoring goals before writing questions.
2. Read `formhug://field-types` and the relevant per-type resources. If direct resource access is unavailable, call `read_reference` with the same URI. Use only field types and shapes supported by the current MCP.
3. Draft the complete scoring plan before calling a write tool:
   - For a quiz `radio`, `checkbox`, or `dropdown` field, set `answers` to one item and use zero-based choice indexes, for example `[{ "answer": [1], "score": 10 }]`.
   - For checkbox questions with multiple correct choices, put every correct zero-based index in the answer array.
   - For text or number quiz questions, use the value shape documented by the MCP.
   - Add concise HTML `answer_explanation` content when explanations improve learning.
   - For assessment choice fields and `likert`, provide one `answers` item per choice, in order. Each item must use its own zero-based index (`[0]`, `[1]`, …); Likert choices are the scale options shared by all statements. For `rating`, provide `rating_max` items (default 5), with index `i` scoring level `i + 1`. Read the relevant field reference before computing the total score, especially for multi-select or multi-statement fields.
   - Keep assessment options balanced in tone and length. Make score direction consistent across every question.
4. Compute the maximum possible score. Design inclusive, non-overlapping feedback ranges that cover the entire `0..maximum` span without gaps, even when required assessment questions make the lowest answered score greater than zero. Match the boundary precision to the configured scores; use adjacent integer ranges such as `0–59`, `60–79`, and `80–100` only when all scores are integers. Make every result label and comment specific to the subject rather than generic filler.
5. Call `create_form` with `scene: "quiz"` or `scene: "assessment"`, the complete scored fields, and one or two concrete English `header_image` keywords. Do not pass api_codes on new fields. Use `list_folders` only when folder placement is requested; never reuse hard-coded folder tokens.
6. Treat `score_based_feedbacks` as a normal finishing step for quizzes and assessments. Unless the user asks for score-only behavior or another post-submission outcome, configure a complete scored experience with `update_form_settings`, `after_submission.mode: "report"`, `after_submission.report.score_based_feedbacks`, and useful submission options such as field numbering or progress.
7. Add conditional logic only after `get_form` returns the generated field and

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: formhug-improve-form
description: Audit and improve an existing FormHug form for clarity, completion friction, field order, required fields, mobile usability, pagination, conditional logic, settings, and visual consistency. Use when the user asks to review, optimize, simplify, fix, or redesign an existing form. Treat review-only requests as read-only. For a quiz or assessment change involving scoring, answers, score ranges, or result feedback, use formhug-create-quiz instead.
---

# Improve an existing FormHug form

Diagnose first, then make the smallest changes that solve the user's problem.

## Inspect

1. Resolve the target with `list_forms` when the token is unknown. Prefer its name filter when a name is known; if the target is not on the first page, follow `next_cursor` until found or the list is exhausted. If several forms match, ask the user to choose rather than guessing.
2. Use `get_form` and `preview_form` to inspect structure and api_codes. Read `get_form_settings`, `get_form_theme`, and `get_field_rules` when the requested review touches behavior, appearance, or conditional logic.
3. Consult the current MCP resources only as needed:
   - `formhug://field-types` for field suitability and advanced shapes.
   - `formhug://field-rules` for conditional behavior.
   - `formhug://themes` for visual changes.
   If direct resource access is unavailable, call `read_reference` with the same URI.

## Diagnose

Evaluate the form against its stated purpose and audience:

- Identify questions that could be removed because they do not support a decision, handoff, or promised respondent outcome.
- Check whether required fields are genuinely necessary.
- Put low-effort questions before sensitive, complex, or open-ended ones.
- Prefer structured field types when downstream filtering or validation matters.
- Check choice completeness, balanced wording, duplicate questions, instructions, locale, timezone, and after-submission behavior.
- Use page breaks only when a classic form is long enough to benefit. Remember that classic pagination requires zero or at least two correctly placed `page_break` fields.
- Verify that conditional targets follow their triggers and that rule api_codes still exist.
- Review the theme for readability and consistency, not merely decoration.
- Flag unnecessary collection or exposure of personal and sensitive data.

Return prioritized findings before mutating anything when the user asked only for an audit, critique, or recommendations.

## Apply requested improvements

An explicit request to optimize, fix, or apply changes authorizes non-destructive improvements. Ask for additional authorization only for the destructive or data-affecting operations listed below.

1. Re-read the latest form state immediately before writing if the review and edit are separated by discussion.
2. Use the narrowest tool for each change: `update_form`, `add_fields`, `update_fields`, `move_field`, `remove_field`, `update_form_settings`, `update_form_theme`, or `update_field_rules`.
3. Preserve data and identifiers:
   - Include the existing field api_code in every `update_fields` item.
   - Never change a field's `type` through `update_fields`; field types are immutable after creation.
   - Treat a type change as a migration: add a replacement field, repair affected rules, and remove the old field only after explicit user authorization. Warn that existing response values remain attached to the old field and are not migrated automatically.
   - Treat nested arrays as replacements. Include every existing choice, statement, dimension, or item that should remain, with its api_code.
   - Treat `update_form_settings` and `update_form_theme` as partial merges: omitted keys remain unchanged, while explicit `null` clears a value.
   - Read current field rules before structural edits that can invalidate their trigger or target api_codes. In `update_field_rules`, each included rule key replaces that rule kind's complete list, `[]` cle

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.