Build, publish and read scored forms, quizzes and calculators. Answers carry points into a score, the score decides the next screen, and published forms are served as static HTML.
Scored across 10 tools
Each tool targets a distinct resource and action: form CRUD (create/get/list/update), publish state (publish/unpublish), and response access (list/get/export) plus analytics are clearly separated. The only adjacent pair, list_responses vs export_responses, is distinguished by paginated JSON vs raw CSV and the descriptions explicitly cross-reference each other.
All ten tools use the same foxform_ prefix followed by a verb_noun pattern (create_form, get_form, list_responses, publish_form, etc.). No camelCase or stylistic deviations, and verbs (create/get/list/update/publish/unpublish/export) consistently reflect the action.
Ten tools is a well-scoped surface for a form-building platform: enough to cover authoring, publishing, response retrieval, and analytics without redundant operations. Each tool earns its place and there are no obvious filler tools.
Form CRUD is covered for create, get, list, and update, with publish/unpublish and full response/analytics access. The main gap is a delete_form operation, leaving no way to permanently remove or archive a form; unpublish only takes it offline.
Create a new form, including per-screen conditional logic. Requires a WRITE-scoped API key.
Args:
title (string): form title (required)
description (string, optional)
theme (string, optional): one of amber|base|midnight|ocean|sunset|forest|lavender|minimal (default amber, the copper-to-amber FoxForm theme)
questions (array, optional): array of screen objects ({ id, type, title, required, variableName?, choices?, logic?, ... }); omit to start empty
thank_you_message (string, optional)
format ('single_question' | 'single_page' | 'chatbot', optional): how the form is presented (see below)
sections (array, optional): single_page page groups, [{ id }]
chatbot_skin ('instagram' | 'whatsapp', optional): chatbot chrome
chatbot_profile (object, optional): chatbot header profile ({ name, handle, followers_text, phone, status, verified, avatar_url })
Returns: { form } with the created form (including its id and slug). The form starts as a draft — call foxform_publish_form to make it live.
Screen fields are validated: unknown fields are REJECTED instead of being stored and ignored, and branching rules are cross-checked against the screen ids in the same payload.
Form format (DEVF-296 / DEVF-322): pass format to choose how the form is presented.
'single_question' (default): one screen at a time (classic).
'single_page': every screen on one scrollable page. Optionally group screens into pages with sections: [{ id }] in order (the 'Section N' label comes from position; no editable title).
'chatbot': an Instagram/WhatsApp DM-style conversation. Set chatbot_skin ('instagram' | 'whatsapp', default instagram) and chatbot_profile (all fields optional, each with a fallback). The question/branching engine is unchanged — only the presentation differs.
These fields require the account's form-format feature to be enabled (live in production); when off the API ignores them and the form stays single_question.
End screen ('end'): title + description, an optional button (buttonEnabled false hides it; buttonText, buttonLink, buttonOpenNewTab) and an optional automatic redirect after submit: autoRedirect true + autoRedirectUrl (absolute http/https URL; the form link's query params such as utm_* are passed along and {{param}} tokens are filled from them) + autoRedirectDelay (seconds 0-10, default 3). The response is recorded before the redirect; respondents see a "Redirecting in N s" line with a "Go now" link.
CONDITIONAL LOGIC (branching), per screen — stored in questions[].logic:
logic.conditionalNavigationV2 = { enabled: true, groups: [ // groups are OR-joined; FIRST matching group wins { id: "grp-1", conditions: [ // conditions inside a group are AND-joined { id: "cond-1", left: "{{quer_testar}}", operator: "equal_to", right: "Ainda não" } ], then: { type: "specific_screen", targetScreenId: "s-motivos" } } ] }
then.type: 'next_screen' | 'previous_screen' | 'specific_screen' (needs targetScreenId = another screen's id) | 'end_form'.
Add then.url (+ optional openNewTab) to redirect to an external URL instead.
operator: 'equal_to' | 'not_equal_to' | 'greater_than' | 'greater_or_equal_than' | 'less_than' | 'less_or_equal_than' | 'contains'.
left/right are EXPRESSION strings: a literal ("10", "Ainda não"), a variable ("{{score}}", "{{minha_var}}" = the screen's variableName), or arithmetic ("calc({{peso}}/(({{altura}}/100)*({{altura}}/100)))").
Comparing an ANSWER: use left: "{{<variableName of the deciding screen>}}" and right = the option's label OR its value (both match).
{{score}} is the running sum of points on the options picked so far (choices[].points, images[].points) — that is how score-based branching works.
A navigation group with no conditions NEVER matches. enabled: false stores the rules but disables them.
Screen-level conditional display uses the same group shape: logic.display = { enabled: true, groups: [...], showAfterSeconds?: n } (then is ignored — THEN means "show").
Other logic keys: logic.autoAdvance = { enabled, delaySeconds? }, logic.navigationBehavior = { onButtonClick?, onAutoAdvance?, targetScreenId? }.
logic.conditionalNavigation (legacy, pre-DEVF-161) is still read and migrated on load — don't author new rules with it.
Unknown fields are REJECTED (they used to be stored and silently ignored): logic as an array, or rules/branching/conditions/goto/jump/nextScreen anywhere, are not read by any renderer.
| Name | Required | Description | Default |
|---|---|---|---|
| theme | No | Theme key: amber|base|midnight|ocean|sunset|forest|lavender|minimal (default amber) | |
| title | Yes | Form title | |
| format | No | Form format: 'single_question' (default — one screen at a time), 'single_page' (all screens on one scrollable page, grouped by `sections`), or 'chatbot' (an Instagram/WhatsApp DM-style conversation; set `chatbot_skin` + `chatbot_profile`). | |
| sections | No | single_page only: the page groups as `[{ id }]`, in order. The 'Section N' label is derived from position; sections have no editable title. | |
| questions | No | Screen objects; omit for an empty form. Conditional logic goes in each screen's `logic` (see the tool description). | |
| description | No | Optional description | |
| chatbot_skin | No | chatbot only: chat chrome to imitate — 'instagram' (default) or 'whatsapp'. | |
| chatbot_profile | No | chatbot only: the profile shown in the chat header. | |
| thank_you_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Well beyond the annotations, it discloses that unknown screen fields are REJECTED (a behavior change from silent ignoring), that branching rules are cross-checked against screen ids in the same payload, and that format-related fields are silently ignored unless the account's feature is enabled. That last item is critical: a call can succeed while the requested format is dropped, which no annotation conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, args, and returns before the deep reference material, which is the right order for a 9-parameter nested tool. It is long but the complexity justifies most of it; the main waste is the 'unknown fields are REJECTED' warning appearing twice and the theme enum being restated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the return shape ({ form } with id and slug), the draft/live lifecycle, validation failure modes, feature-flag degradation, and redirect semantics including query-param passing. With no output schema present, the description supplying the return contract is exactly what's needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 89%, so the baseline would be 3, but the description adds substantial meaning: the default theme rationale, the full `questions[].logic` grammar (then.type, operator enum, expression syntax, {{score}} semantics, {{param}} substitution), and the end-screen field set with the 0-10 delay bound. The schema itself defers to the description for logic, so this carries real weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a new form') and immediately scopes it to include per-screen conditional logic, which distinguishes it from foxform_update_form. The access requirement ('Requires a WRITE-scoped API key') is stated in the first line, so an agent can rule itself in or out instantly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the follow-on step: the form 'starts as a draft — call foxform_publish_form to make it live', and 'omit to start empty' clarifies the minimal call. It does not state when to prefer foxform_update_form over creating a new form, but the create/update split is largely self-evident from the names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export all responses for a form as CSV text (one row per response, columns = questions). Large exports are truncated — use foxform_list_responses with pagination for very large datasets.
Args:
form_id (string)
Returns: raw CSV text.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Form ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only and non-destructive. The description adds meaningful behavioral context beyond that: it returns raw CSV text, and it truncates large exports. This is essential for an agent deciding whether this tool is safe and suitable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: it opens with the core function, then the truncation caveat, then the args and return value. Every sentence contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with rich annotations and no output schema, the description covers the return format, the key limitation, and the alternative for large datasets. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents form_id with 100% coverage, so the baseline is 3. The description merely repeats 'form_id (string)' and does not add meaningful detail about format, constraints, or edge cases beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Export'), a clear resource ('all responses for a form'), and the output format ('CSV text'). It also explains the row/column structure, which distinguishes it from listing or fetching individual responses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns that large exports are truncated and directs the agent to use foxform_list_responses with pagination for very large datasets. This gives clear when-to-use and when-not-to-use guidance relative to a relevant sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single form by ID, including its full question list, per-screen conditional logic and settings.
Args:
form_id (string): the form's ID (from foxform_list_forms)
response_format ('markdown' | 'json')
Returns { form, public_url }: the full form object (id, title, description, slug, status, theme, questions[], thank_you_message, timestamps, plus format and — when set — sections, chatbot_skin, chatbot_profile) plus public_url — the public link (https://forms.foxform.app/<slug>), which is live only when status is 'published'. Use public_url verbatim; never build the URL yourself (the public domain is forms.foxform.app, not foxform.app).
Each screen in questions[] carries its own logic (branching / conditional display) and, for choice screens, choices[]/images[] with their points and value. The markdown output summarises every rule; use response_format 'json' to get the exact stored objects (that's the shape foxform_update_form expects back).
Form format (DEVF-296 / DEVF-322): pass format to choose how the form is presented.
'single_question' (default): one screen at a time (classic).
'single_page': every screen on one scrollable page. Optionally group screens into pages with sections: [{ id }] in order (the 'Section N' label comes from position; no editable title).
'chatbot': an Instagram/WhatsApp DM-style conversation. Set chatbot_skin ('instagram' | 'whatsapp', default instagram) and chatbot_profile (all fields optional, each with a fallback). The question/branching engine is unchanged — only the presentation differs.
These fields require the account's form-format feature to be enabled (live in production); when off the API ignores them and the form stays single_question.
End screen ('end'): title + description, an optional button (buttonEnabled false hides it; buttonText, buttonLink, buttonOpenNewTab) and an optional automatic redirect after submit: autoRedirect true + autoRedirectUrl (absolute http/https URL; the form link's query params such as utm_* are passed along and {{param}} tokens are filled from them) + autoRedirectDelay (seconds 0-10, default 3). The response is recorded before the redirect; respondents see a "Redirecting in N s" line with a "Go now" link.
CONDITIONAL LOGIC (branching), per screen — stored in questions[].logic:
logic.conditionalNavigationV2 = { enabled: true, groups: [ // groups are OR-joined; FIRST matching group wins { id: "grp-1", conditions: [ // conditions inside a group are AND-joined { id: "cond-1", left: "{{quer_testar}}", operator: "equal_to", right: "Ainda não" } ], then: { type: "specific_screen", targetScreenId: "s-motivos" } } ] }
then.type: 'next_screen' | 'previous_screen' | 'specific_screen' (needs targetScreenId = another screen's id) | 'end_form'.
Add then.url (+ optional openNewTab) to redirect to an external URL instead.
operator: 'equal_to' | 'not_equal_to' | 'greater_than' | 'greater_or_equal_than' | 'less_than' | 'less_or_equal_than' | 'contains'.
left/right are EXPRESSION strings: a literal ("10", "Ainda não"), a variable ("{{score}}", "{{minha_var}}" = the screen's variableName), or arithmetic ("calc({{peso}}/(({{altura}}/100)*({{altura}}/100)))").
Comparing an ANSWER: use left: "{{<variableName of the deciding screen>}}" and right = the option's label OR its value (both match).
{{score}} is the running sum of points on the options picked so far (choices[].points, images[].points) — that is how score-based branching works.
A navigation group with no conditions NEVER matches. enabled: false stores the rules but disables them.
Screen-level conditional display uses the same group shape: logic.display = { enabled: true, groups: [...], showAfterSeconds?: n } (then is ignored — THEN means "show").
Other logic keys: logic.autoAdvance = { enabled, delaySeconds? }, logic.navigationBehavior = { onButtonClick?, onAutoAdvance?, targetScreenId? }.
logic.conditionalNavigation (legacy, pre-DEVF-161) is still read and migrated on load — don't author new rules with it.
Unknown fields are REJECTED (they used to be stored and silently ignored): logic as an array, or rules/branching/conditions/goto/jump/nextScreen anywhere, are not read by any renderer.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Form ID | |
| response_format | No | Output format: 'markdown' (human-readable) or 'json' (machine-readable) | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only/idempotent/non-destructive profile, and the description adds genuinely non-obvious behavior: public_url is live only when status is 'published', the URL must be used verbatim because the public domain differs from the API domain, and markdown output only summarises rules while json returns exact stored objects. These are constraints the schema cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening two paragraphs are front-loaded and earn their place, but the bulk of the text is authoring documentation for conditional logic (groups, operators, expression syntax, legacy keys) and format/section/chatbot/end-screen configuration that only matters to foxform_create_form / foxform_update_form. Statements like 'Unknown fields are REJECTED' are irrelevant to a tool with two fixed parameters, so the length is not justified for this operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a deeply nested return object, the description carries a real burden and mostly meets it: it enumerates the form object's fields, explains public_url liveness, and explains that each screen carries its own logic/choices. It is complete for calling the tool, though the deep-dive into logic authoring belongs to the write tools rather than to reading.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes further by stating where form_id comes from and the practical difference between the two response_format values (markdown summarises, json is the exact round-trippable shape). That is real meaning beyond the enum labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single form by ID') and immediately enumerates what is included (question list, per-screen conditional logic, settings), which distinguishes it from the analytics and list siblings. The return contract ({ form, public_url }) is stated up front.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It does route the agent usefully: form_id comes from foxform_list_forms, and response_format 'json' is the shape foxform_update_form expects back, implying the read-before-update workflow. But there is no explicit contrast with foxform_get_form_analytics or foxform_list_forms, and the instruction 'pass `format` to choose how the form is presented' describes an authoring parameter this read tool does not accept, which can mislead an agent about what it can do here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated analytics for a form: overview KPIs (total responses, form views, response rate, avg response time), the responses-over-time timeline, and per-question stats.
Args:
form_id (string)
response_format ('markdown' | 'json')
Returns: { overview, timeline: [{date,count}], questions: [...], response_time_distribution?, views_timeline? }. Note: form_views / response_rate are null until the form has tracked views (forward-only).
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Form ID | |
| response_format | No | Output format: 'markdown' (human-readable) or 'json' (machine-readable) | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by warning that form_views and response_rate remain null until views are tracked (forward-only), which is not visible in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the analytics summary. The Args block is somewhat redundant with the schema, but the return outline and forward-only note earn their place, and the overall structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description carries the burden of explaining return values, and it does so with a top-level shape and timeline item structure. It also documents an important nullability edge case, though it could have specified per-question entry fields and how response_format affects the returned payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented. The Args section in the description mostly repeats the schema (form_id string, response_format enum/default), adding little new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a precise verb and resource: retrieving aggregated analytics for a form. It enumerates concrete contents (KPIs, responses-over-time timeline, per-question stats), which clearly separates it from siblings like list_responses or get_form.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the description: choose this tool when you need aggregated analytics rather than raw responses or form configuration. However, it does not explicitly mention alternatives or state when not to use it, so guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one response by its ID (from foxform_list_responses).
Args:
response_id (string)
response_format ('markdown' | 'json')
Returns the full response object (id, form_id, answers, submitted_at, metadata).
| Name | Required | Description | Default |
|---|---|---|---|
| response_id | Yes | Response ID | |
| response_format | No | Output format: 'markdown' (human-readable) or 'json' (machine-readable) | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds the return shape ('full response object' with key fields) and the ID source, which is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized into a one-line summary, an Args list, and a Returns section. There is no filler or redundancy; every line adds either scope, parameter semantics, or return information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID operation with two parameters, rich annotations, and a fully documented schema, the description provides enough context to invoke the tool correctly. It also supplies the return object's key fields, compensating for the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters fully described including the enum values and default for response_format. The description mostly restates the schema, though it does add the useful hint that response_id comes from foxform_list_responses.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Fetch') and resource ('one response by its ID'), making the tool's scope immediately clear. Referring to foxform_list_responses as the source of the ID helps differentiate it from the list and export siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'one response by its ID (from foxform_list_responses)' implies the intended workflow: first list responses to obtain an ID, then fetch a single one. It does not explicitly enumerate alternatives such as export_responses for bulk retrieval, but the single-response framing provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the forms owned by the authenticated FoxForm account, newest first.
Args:
page (number): 1-based page number (default 1)
limit (number): page size, 1-100 (default 20)
response_format ('markdown' | 'json'): output format (default markdown)
Returns: { total, page, limit, count, forms: [{ id, title, status, slug, public_url, questions_count, updated_at }] }
The public link of a form is public_url (https://forms.foxform.app/<slug>) — always use this exact value, do NOT build the URL yourself (the public domain is forms.foxform.app, not foxform.app). public_url is only live when status is 'published'.
Use this first to discover form IDs, then call foxform_get_form / foxform_get_form_analytics.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number | |
| limit | No | Page size (1-100) | |
| response_format | No | Output format: 'markdown' (human-readable) or 'json' (machine-readable) | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/idempotent behavior, and the description adds valuable operational detail: forms return newest first, public_url must be used exactly as provided, and public_url is only live when status is 'published'. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured, with the core behavior first, followed by parameters, return shape, and a crucial URL caveat. Some repetition of schema details exists, but every section serves a purpose and no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the inline Returns block is essential and fully provided. The description also covers the non-obvious public_url domain caveat, the published-status dependency, and the recommended follow-up tools, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents page, limit, and response_format. The description mostly repeats these details and adds no significant semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists forms owned by the authenticated account, sorted newest first, which is a specific verb and resource. It distinguishes this from form creation, response listing, and analytics tools by framing it as the discovery entry point for form IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit workflow guidance: use this first to discover form IDs, then call foxform_get_form or foxform_get_form_analytics. It does not exhaustively enumerate when not to use it versus list_responses, but the stated workflow is clear enough for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List submitted responses for a form, newest first.
Args:
form_id (string): the form's ID
page (number): 1-based page (default 1)
limit (number): page size, 1-100 (default 20)
response_format ('markdown' | 'json')
Returns: { total, page, limit, count, responses: [{ id, submitted_at, answers }] }. For aggregate metrics use foxform_get_form_analytics; for a full dump use foxform_export_responses.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| form_id | Yes | Form ID | |
| response_format | No | Output format: 'markdown' (human-readable) or 'json' (machine-readable) | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond those: newest-first ordering, 1-based pagination with defaults, page size limits, and the exact return envelope. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and scannable, with a clear Args/Returns layout and a single closing sentence for alternative tools. The Args section repeats some schema information, which slightly reduces its efficiency, but overall it is compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description provides the return shape, ordering, and pagination contract, which is essential for an agent. The only notable gap is not explicitly stating how response_format affects the `answers` field in the returned responses, though the schema's human-readable vs machine-readable note partially covers this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 50%, the description compensates by covering all four parameters and adding '1-based' for page and 'page size, 1-100' for limit. However, it also restates schema defaults and min/max for limit and duplicates form_id, so the additional semantic value is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List submitted responses for a form, newest first' – a specific verb, resource, and ordering qualifier. It also names sibling alternatives for different needs, and the plural 'responses' clearly distinguishes it from foxform_get_response.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use alternatives: 'For aggregate metrics use foxform_get_form_analytics; for a full dump use foxform_export_responses.' This provides concrete routing guidance rather than leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a form so it's live at its public URL and can accept responses. Requires a WRITE-scoped API key.
Args:
form_id (string)
Returns: { form, public_url } — the published form (status 'published') and its live public link https://forms.foxform.app/<slug>. When sharing the link with the user, use public_url EXACTLY as returned; do NOT build the URL yourself (the public domain is forms.foxform.app, NOT foxform.app or the API/app domain). (May fail with a plan-limit error on Free accounts.)
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Form ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint and destructiveHint absent, and the description adds valuable behavioral context: the WRITE-scoped key requirement, the specific public_url usage rule (do not construct yourself), and the possibility of a plan-limit failure. These go beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet complete, front-loading the purpose and then providing necessary constraints (auth, URL usage, failure mode) in a logical order. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter action with annotations present, the description covers all essential information: prerequisites, return shape, URL handling, and a known failure case. An agent has everything needed to call the tool correctly without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with a description for form_id, so the description does not need to elaborate. It simply restates the parameter name and type, adding no extra meaning beyond what the schema supplies. The baseline of 3 applies because schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and the resource 'form', along with the effect: making it live at a public URL and accepting responses. It is distinct from sibling tools like unpublish by its action, but it does not explicitly name alternatives, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is the prerequisite 'Requires a WRITE-scoped API key', which is a condition, not a when-to-use instruction. It does not say when to prefer this over other tools (e.g., for a draft form), nor does it mention when not to use it. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unpublish a form (takes it offline; stops accepting responses). Requires a WRITE-scoped API key.
Args:
form_id (string)
Returns: a confirmation message.
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | Form ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already supply readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds complementary context by stating the concrete behavior (takes the form offline, stops responses), the auth requirement, and the return value (confirmation message). It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the verb and immediate effect appear first, followed by the auth requirement and a brief args/returns structure. There is no filler, and every sentence contributes operational knowledge.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter toggle operation, the description plus annotations cover the action, effect, auth, safety profile, and return type. It does not describe the exact confirmation message format or mention the relationship to foxform_publish_form, but those are minor gaps for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter with a description ('Form ID'), so the baseline is 3. The description merely repeats 'form_id (string)' without adding meaning beyond the schema, such as accepted formats, lifecycle requirements, or error cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource—'Unpublish a form'—and immediately clarifies the meaning with 'takes it offline; stops accepting responses.' This clearly distinguishes it from read-only siblings and the opposite action foxform_publish_form without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose itself implies when to use the tool: when a form should stop accepting responses. It also adds a practical prerequisite by requiring a WRITE-scoped API key. However, it never explicitly names alternatives, says 'use this instead of X,' or explains when not to use it—leaving the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing form's fields, including each screen's conditional logic (branching). Requires a WRITE-scoped API key. Only the fields you pass are changed.
Args:
form_id (string): the form to update (required)
title (string, optional)
description (string, optional)
theme (string, optional): one of amber|base|midnight|ocean|sunset|forest|lavender|minimal
questions (array, optional): replaces the FULL screen list — there is no per-screen patch. To add logic to one screen: call foxform_get_form with response_format 'json', edit that screen's logic, and send the whole array back.
thank_you_message (string, optional)
format ('single_question' | 'single_page' | 'chatbot', optional)
sections (array, optional): single_page page groups, [{ id }]
chatbot_skin ('instagram' | 'whatsapp', optional)
chatbot_profile (object, optional): chatbot header profile ({ name, handle, followers_text, phone, status, verified, avatar_url })
Returns: { form } with the updated form.
Screen fields are validated: unknown fields are REJECTED instead of being stored and ignored (the API accepts arbitrary keys but no renderer reads them), then.targetScreenId must be the id of a screen in the same payload, and {{variables}} that no screen exposes come back as warnings.
Form format (DEVF-296 / DEVF-322): pass format to choose how the form is presented.
'single_question' (default): one screen at a time (classic).
'single_page': every screen on one scrollable page. Optionally group screens into pages with sections: [{ id }] in order (the 'Section N' label comes from position; no editable title).
'chatbot': an Instagram/WhatsApp DM-style conversation. Set chatbot_skin ('instagram' | 'whatsapp', default instagram) and chatbot_profile (all fields optional, each with a fallback). The question/branching engine is unchanged — only the presentation differs.
These fields require the account's form-format feature to be enabled (live in production); when off the API ignores them and the form stays single_question.
End screen ('end'): title + description, an optional button (buttonEnabled false hides it; buttonText, buttonLink, buttonOpenNewTab) and an optional automatic redirect after submit: autoRedirect true + autoRedirectUrl (absolute http/https URL; the form link's query params such as utm_* are passed along and {{param}} tokens are filled from them) + autoRedirectDelay (seconds 0-10, default 3). The response is recorded before the redirect; respondents see a "Redirecting in N s" line with a "Go now" link.
CONDITIONAL LOGIC (branching), per screen — stored in questions[].logic:
logic.conditionalNavigationV2 = { enabled: true, groups: [ // groups are OR-joined; FIRST matching group wins { id: "grp-1", conditions: [ // conditions inside a group are AND-joined { id: "cond-1", left: "{{quer_testar}}", operator: "equal_to", right: "Ainda não" } ], then: { type: "specific_screen", targetScreenId: "s-motivos" } } ] }
then.type: 'next_screen' | 'previous_screen' | 'specific_screen' (needs targetScreenId = another screen's id) | 'end_form'.
Add then.url (+ optional openNewTab) to redirect to an external URL instead.
operator: 'equal_to' | 'not_equal_to' | 'greater_than' | 'greater_or_equal_than' | 'less_than' | 'less_or_equal_than' | 'contains'.
left/right are EXPRESSION strings: a literal ("10", "Ainda não"), a variable ("{{score}}", "{{minha_var}}" = the screen's variableName), or arithmetic ("calc({{peso}}/(({{altura}}/100)*({{altura}}/100)))").
Comparing an ANSWER: use left: "{{<variableName of the deciding screen>}}" and right = the option's label OR its value (both match).
{{score}} is the running sum of points on the options picked so far (choices[].points, images[].points) — that is how score-based branching works.
A navigation group with no conditions NEVER matches. enabled: false stores the rules but disables them.
Screen-level conditional display uses the same group shape: logic.display = { enabled: true, groups: [...], showAfterSeconds?: n } (then is ignored — THEN means "show").
Other logic keys: logic.autoAdvance = { enabled, delaySeconds? }, logic.navigationBehavior = { onButtonClick?, onAutoAdvance?, targetScreenId? }.
logic.conditionalNavigation (legacy, pre-DEVF-161) is still read and migrated on load — don't author new rules with it.
Unknown fields are REJECTED (they used to be stored and silently ignored): logic as an array, or rules/branching/conditions/goto/jump/nextScreen anywhere, are not read by any renderer.
| Name | Required | Description | Default |
|---|---|---|---|
| theme | No | ||
| title | No | ||
| format | No | Form format: 'single_question' (default — one screen at a time), 'single_page' (all screens on one scrollable page, grouped by `sections`), or 'chatbot' (an Instagram/WhatsApp DM-style conversation; set `chatbot_skin` + `chatbot_profile`). | |
| form_id | Yes | Form ID | |
| sections | No | single_page only: the page groups as `[{ id }]`, in order. The 'Section N' label is derived from position; sections have no editable title. | |
| questions | No | Replaces the full screen list. Conditional logic goes in each screen's `logic` (see the tool description). | |
| description | No | ||
| chatbot_skin | No | chatbot only: chat chrome to imitate — 'instagram' (default) or 'whatsapp'. | |
| chatbot_profile | No | chatbot only: the profile shown in the chat header. | |
| thank_you_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive/open-world annotations, the description discloses important mutation behavior: questions replaces the full screen list, there is no per-screen patch, unknown fields are rejected rather than ignored, conditional target screen IDs are validated, and feature-flagged format fields may be silently ignored. It also explains the redirect behavior and validation warnings, providing rich context for a destructive update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but mostly justified by the complexity of conditional-logic authoring, and it is well front-loaded with purpose, usage, and argument semantics. Some repetition exists, notably the unknown-fields rejection warning appearing twice, which keeps it from being maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, nested conditional-logic objects, no output schema, and destructive annotations, the description is exceptionally complete. It covers parameters, validation rules, full replacement caveats, format presentation behavior, end-screen redirects, and conditional branching syntax, leaving little ambiguity for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite only 60% schema description coverage, the description documents every parameter's meaning and constraints, including theme enum values, format-specific fields, sections behavior, chatbot_skin/chatbot_profile details, and the full replacement semantics of questions. It adds substantial meaning beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Update an existing form's fields, including each screen's conditional logic (branching)." That clearly distinguishes it from sibling tools such as foxform_create_form and foxform_get_form, and the scope is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage context, including the WRITE-scoped API key requirement and the crucial distinction that only passed fields change. It also names an alternative workflow for editing one screen's logic: call foxform_get_form with response_format 'json', edit that screen, then resend the full questions array. It does not broadly contrast with create/publish/unpublish, but the update-specific guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
foxform_create_form1 field changedInput schema / properties / theme / descriptionPrevious value: -"Theme key (default sunset/Ember)"New value: +"Theme key: amber|base|midnight|ocean|sunset|forest|lavender|minimal (default amber)"foxform_create_form4 fields changedInput schema / properties / chatbot_profileAdded value: +{
+ "additionalProperties": false,
+ "description": "chatbot only: the profile shown in the chat header.",
+ "properties": {
+ "avatar_url": {
+ "description": "Avatar image URL; falls back to the name's initials.",
+ "type": "string"
+ },
+ "followers_text": {
+ "description": "Free text under the name, e.g. followers/posts (Instagram only).",
+ "type": "string"
+ },
+ "handle": {
+ "description": "Instagram @handle (Instagram skin only).",
+ "type": "string"
+ },
+ "name": {
+ "description": "Display name in the chat header (both skins; default 'Sua Marca').",
+ "type": "string"
+ },
+ "phone": {
+ "description": "Shown phone number (WhatsApp skin only).",
+ "type": "string"
+ },
+ "status": {
+ "description": "Header status line (both skins; empty on WhatsApp shows the phone).",
+ "type": "string"
+ },
+ "verified": {
+ "description": "Blue verified badge (Instagram only; default true).",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+}Input schema / properties / chatbot_skinAdded value: +{
+ "description": "chatbot only: chat chrome to imitate — 'instagram' (default) or 'whatsapp'.",
+ "enum": [
+ "instagram",
+ "whatsapp"
+ ],
+ "type": "string"
+}Input schema / properties / formatAdded value: +{
+ "description": "Form format: 'single_question' (default — one screen at a time), 'single_page' (all screens on one scrollable page, grouped by `sections`), or 'chatbot' (an Instagram/WhatsApp DM-style conversation; set `chatbot_skin` + `chatbot_profile`).",
+ "enum": [
+ "single_question",
+ "single_page",
+ "chatbot"
+ ],
+ "type": "string"
+}Input schema / properties / sectionsAdded value: +{
+ "description": "single_page only: the page groups as `[{ id }]`, in order. The 'Section N' label is derived from position; sections have no editable title.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}foxform_update_form4 fields changedInput schema / properties / chatbot_profileAdded value: +{
+ "additionalProperties": false,
+ "description": "chatbot only: the profile shown in the chat header.",
+ "properties": {
+ "avatar_url": {
+ "description": "Avatar image URL; falls back to the name's initials.",
+ "type": "string"
+ },
+ "followers_text": {
+ "description": "Free text under the name, e.g. followers/posts (Instagram only).",
+ "type": "string"
+ },
+ "handle": {
+ "description": "Instagram @handle (Instagram skin only).",
+ "type": "string"
+ },
+ "name": {
+ "description": "Display name in the chat header (both skins; default 'Sua Marca').",
+ "type": "string"
+ },
+ "phone": {
+ "description": "Shown phone number (WhatsApp skin only).",
+ "type": "string"
+ },
+ "status": {
+ "description": "Header status line (both skins; empty on WhatsApp shows the phone).",
+ "type": "string"
+ },
+ "verified": {
+ "description": "Blue verified badge (Instagram only; default true).",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+}Input schema / properties / chatbot_skinAdded value: +{
+ "description": "chatbot only: chat chrome to imitate — 'instagram' (default) or 'whatsapp'.",
+ "enum": [
+ "instagram",
+ "whatsapp"
+ ],
+ "type": "string"
+}Input schema / properties / formatAdded value: +{
+ "description": "Form format: 'single_question' (default — one screen at a time), 'single_page' (all screens on one scrollable page, grouped by `sections`), or 'chatbot' (an Instagram/WhatsApp DM-style conversation; set `chatbot_skin` + `chatbot_profile`).",
+ "enum": [
+ "single_question",
+ "single_page",
+ "chatbot"
+ ],
+ "type": "string"
+}Input schema / properties / sectionsAdded value: +{
+ "description": "single_page only: the page groups as `[{ id }]`, in order. The 'Section N' label is derived from position; sections have no editable title.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}foxform_create_formfoxform_export_responsesfoxform_get_formfoxform_get_form_analyticsfoxform_get_responsefoxform_list_formsfoxform_list_responsesfoxform_publish_formfoxform_unpublish_formfoxform_update_form
Add one secure layer between your agents and this server.