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: forms (create, get, update, publish, unpublish, list), responses (list, get, export), and analytics. There is no overlap in purpose, and even list vs get vs export for responses are clearly differentiated by their descriptions.
All tools follow a consistent `foxform_<verb>_<noun>` pattern (e.g., create_form, get_form, update_form, list_forms, publish_form). The verbs are consistent (create, get, update, list, export, publish, unpublish) and the nouns are clear (form, response, responses, analytics).
With exactly 10 tools, the server is well-scoped for a form-building platform: it covers form CRUD, lifecycle (publish/unpublish), response retrieval/export, and analytics. Each tool has a distinct and necessary function, and the count is in the ideal 3-15 range.
The tool surface covers the full form lifecycle (create, get, update, publish, unpublish, list) and response handling (list, get, export, analytics). Minor gaps exist, such as lack of a tool to delete forms or to update/delete individual responses, but these are not critical for typical workflows and do not create dead ends.
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.
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 |
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.
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 mark this readOnly/idempotent, and the description goes well beyond them: it details the return structure, warns that public_url is only live when status is 'published', tells the agent never to build the URL manually, explains feature-flag gating of format fields, and documents that unknown fields are rejected. This is rich, non-obvious behavioral context.
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 it is well-structured with clear headers, lists, and a logical flow from purpose to args to returns to format variants to conditional-logic details. Some sections (e.g., exhaustive logic documentation) go deeper than strictly needed for a fetch operation, but each part serves interpreting the returned form object.
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 description carries the full burden of explaining return values — and it does so thoroughly: full object shape, public_url behavior, format variants, conditional logic structure, legacy fields, and rejection semantics. Nothing needed to call or interpret the tool correctly is missing.
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%, but the description adds real value: it tells where to obtain form_id (from foxform_list_forms) and explains the practical difference between markdown and json outputs, including that json returns the exact shape update_form expects. That goes beyond the schema's bare descriptions.
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 'Fetch a single form by ID, including its full question list, per-screen conditional logic and settings' — a specific verb, resource, and scope. This clearly distinguishes it from list_forms (fetching all) and update_form (mutating).
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 states the form_id comes from foxform_list_forms and explains when to choose response_format 'json' (when the exact stored object shape is needed for foxform_update_form). It doesn't explicitly list exclusions versus other sibling tools, but the retrieval purpose is unmistakable and the formatting guidance is actionable.
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.
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 |
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.