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/list/publish/unpublish), responses (list/get/export), and analytics. Even list_responses and export_responses are clearly differentiated by pagination vs. full CSV export.
All tools follow the exact same foxform_verb_noun pattern in snake_case, e.g. foxform_create_form, foxform_list_responses, foxform_publish_form. There are no mixed conventions or vague verbs.
Ten tools is well-scoped for a form management server. Each tool covers a necessary aspect of form lifecycle, response retrieval, or analytics without redundant or filler operations.
The surface covers form creation, retrieval, updating, publishing/unpublishing, response listing, export, and analytics. The main gap is the absence of a delete_form tool, so agents cannot fully remove forms, though they can work around it by unpublishing.
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 midnight|ocean|sunset|forest|lavender|minimal (default sunset = Ember)
questions (array, optional): array of screen objects ({ id, type, title, required, variableName?, choices?, logic?, ... }); omit to start empty
thank_you_message (string, optional)
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.
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 (default sunset/Ember) | |
| title | Yes | Form 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 | |
| thank_you_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse annotations, the description reveals important behaviors: the return shape, draft lifecycle, strict validation that rejects unknown fields, migration of legacy logic, and detailed interpretation rules for conditional groups. This substantially helps an agent anticipate side effects and validation failures.
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 appropriately so for a complex form-creation tool with branching logic and no output schema. It is well organized: creation behavior first, then arguments, then the conditional-logic specification, and every section provides actionable detail without 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 tool with 5 parameters, no output schema, and limited annotations, the description covers the return value, lifecycle, authentication requirement, validation strictness, legacy behavior, and full branching semantics. Nothing essential for correct invocation 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 80%, but the description adds significant semantics: the exact theme enum values and default, the screen object shape for questions, and a complete conditional-logic reference for questions[].logic including operators, expressions, and navigation types. This goes well beyond the schema's short 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 states a specific verb and resource: 'Create a new form', and adds the distinguishing capability 'including per-screen conditional logic'. This clearly separates it from siblings like foxform_update_form, foxform_get_form, and foxform_publish_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 description gives clear context: requires a WRITE-scoped key, omit questions to start empty, and the created form is a draft that must be published via foxform_publish_form. It does not explicitly say 'use foxform_update_form to edit existing forms', but the sibling names make that obvious.
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 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).
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 cover read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral context beyond that: public_url is only live when status is 'published', URLs must not be hand-built, markdown summarizes logic while json exposes exact stored objects, unknown fields are rejected, and legacy conditionalNavigation is migrated on load. These details meaningfully affect how an agent should interpret and use the result.
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 meticulously structured: a one-sentence summary, Args, Returns, then clearly labeled conditional-logic detail. Every section earns its place because the returned object is complex and the logic semantics are non-obvious. The most important operational caveats (public_url, response_format, unknown-field rejection) are front-loaded before the deep-dive.
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 must carry the full burden of explaining the return shape. It does so thoroughly: the top-level form object fields, public_url behavior, questions[] structure, logic object shapes, operators, expression semantics, score mechanics, and legacy fields. An agent can call this tool and correctly consume nearly any response without additional documentation.
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?
Even though schema coverage is 100%, the description enriches both parameters. It tells the agent that form_id comes from foxform_list_forms, and it explains the practical difference between response_format values: markdown summarizes every rule, while json returns exact stored objects matching what foxform_update_form expects. This goes beyond the schema's terse 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 a specific verb and resource: 'Fetch a single form by ID, including its full question list, per-screen conditional logic and settings.' This clearly distinguishes from sibling tools like foxform_list_forms and foxform_get_form_analytics. It also names the source of form_id (foxform_list_forms), reinforcing the tool's exact role.
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 provides clear context: use this tool to retrieve a single full form by ID, and it points users to foxform_list_forms for obtaining valid IDs. It also explains when to choose 'markdown' vs 'json', noting that json returns the exact stored shape that foxform_update_form expects. It does not explicitly state when-not-to-use it relative to analytics or export tools, so it falls just short of a 5.
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)
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)
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.
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 | ||
| form_id | Yes | Form ID | |
| questions | No | Replaces the full screen list. Conditional logic goes in each screen's `logic` (see the tool description). | |
| description | No | ||
| thank_you_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This is exceptionally transparent beyond the annotations: it warns that questions replaces the FULL screen list with no per-screen patch, that unknown fields are REJECTED rather than silently ignored, and that enabled:false stores but disables rules. It also explains validation behavior, legacy migration, and destructive update semantics, all of which align with the destructiveHint 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 long but proportionate to the tool's complexity, with a clear front-loaded purpose followed by structured sections for Args, Returns, validation, and conditional logic. Minor redundancy exists around 'unknown fields are REJECTED,' mentioned twice, which keeps it from a perfect score.
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?
Despite having no output schema and sparse schema descriptions, the description covers return shape, validation rules, auth requirements, the full conditional-logic grammar, and the safe workflow for editing one screen. An agent has enough to invoke the tool correctly and reason about edge cases.
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 only 33%, so the description carries most of the parameter burden. It clearly marks form_id as required, lists all optional fields, and gives deep semantics for questions including the full conditional logic structure. The remaining params like theme and thank_you_message are only labeled optional, but their names and schema types provide enough context.
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 conditional logic. It clearly distinguishes from siblings like foxform_create_form by emphasizing 'existing' and the partial-update behavior ('Only the fields you pass are changed').
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 establishes clear usage context: it requires a WRITE-scoped API key, only changes provided fields, and even prescribes a workflow using foxform_get_form to retrieve and edit a screen's logic. It does not explicitly enumerate when not to use it versus create or publish tools, so it stops short of a 5.
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_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.