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.
Average 4.4/5 across 10 of 10 tools scored. Lowest: 3.9/5.
Each tool pairs a unique action with a unique resource: forms have create/get/update/list/publish/unpublish, responses have list/get/export, and analytics is separate. The only near-overlap (export vs list responses) is explicitly differentiated by truncation and pagination.
All tool names share the foxform_ prefix and follow a strict verb_noun pattern (create_form, list_responses, publish_form). No mixed casing or synonym verbs create ambiguities.
Ten tools is a well-scoped surface for a form management API: form lifecycle, response access, and analytics each have dedicated operations. None feel redundant, and the count stays comfortably within the ideal range.
The core form lifecycle is covered: create, read, update, publish, unpublish, and list. The only notable gap is delete_form (and no response deletion/update), which agents can work around but is still a real missing lifecycle op.
foxform_create_formCreate a FoxForm formAInspectCreate 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.
foxform_export_responsesExport responses as CSVAExport 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.
foxform_get_formGet a FoxForm formAFetch 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 the full form object (id, title, description, slug, status, theme, questions[], thank_you_message, timestamps).
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 mark this as read-only and idempotent, and the description adds substantial behavioral detail: conditional logic semantics (OR/AND joins, first match wins), expression evaluation, score accumulation, legacy conditionalNavigation migration, and rejection of unknown fields. This goes far beyond what the annotations or schema convey.
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 well-structured with clear sections, a code example, and a front-loaded purpose statement. It contains some unavoidable detail because conditional logic is complex, though it could be slightly tightened without losing value.
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 burden of explaining the return value. It lists the full form object fields, describes the questions[] array, choices/images points, and thoroughly documents conditional logic and response_format differences. This is sufficient for an agent to call the tool and interpret its output 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 coverage is 100% and already documents both parameters, so the baseline is 3. The description adds real meaning by explaining that form_id is obtained from foxform_list_forms and that response_format='json' returns the exact shape expected by foxform_update_form. This exceeds the schema's minimal 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 first sentence states a specific verb and resource: 'Fetch a single form by ID', and enumerates the exact contents returned: 'full question list, per-screen conditional logic and settings'. This clearly distinguishes it from list_forms (which lists forms), get_form_analytics (analytics), and update_form (mutation).
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 usage context: form_id comes from foxform_list_forms, and response_format 'json' is recommended when the exact stored object shape is needed for foxform_update_form. It does not explicitly state when to avoid this tool in favor of a sibling, but the context is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
foxform_get_form_analyticsGet form analyticsAAggregated 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.
foxform_get_responseGet a single responseAFetch 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.
foxform_list_formsList FoxForm formsAList 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, questions_count, updated_at }] } 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 cover readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavior beyond that: account scoping, newest-first ordering, pagination, configurable response format, and the exact return object shape. Since there is no output schema, providing the return structure directly in the description is valuable.
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-structured: a one-sentence purpose, a short Args list, a Returns block, and a one-line workflow instruction. Every section earns its place, and the most important usage guidance is front-loaded.
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 read-only, paginated list tool with three optional parameters and no output schema, the description is complete. It covers what is listed, ordering, pagination, response format, return fields, and how the tool fits into the larger workflow with sibling tools. Nothing an agent needs to call it 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 description coverage is 100% and the description largely restates the schema's parameter definitions, defaults, ranges, and enums. It adds little semantic information beyond the existing parameter descriptions. The baseline 3 applies because the schema already carries the burden and the description provides no meaningful extra insight into parameter usage.
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 uses a specific verb and resource ('List the forms owned by the authenticated FoxForm account') and adds the ordering constraint 'newest first'. It clearly distinguishes from sibling tools that target responses, creation, updates, or analytics, and even names the related get_form/get_form_analytics tools for later use.
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 usage context: 'Use this first to discover form IDs, then call foxform_get_form / foxform_get_form_analytics.' This tells an agent when this tool fits in a workflow. It does not, however, spell out when to prefer a sibling like foxform_list_responses or state negative conditions for use, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
foxform_list_responsesList form responsesAList 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.
foxform_publish_formPublish a formAPublish 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 } with status 'published'. (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 this is not read-only, not destructive, and idempotent. The description adds valuable context: the need for a WRITE-scoped API key, the return shape ({ form } with status 'published'), and the possible plan-limit failure on Free accounts. It does not contradict 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?
Every sentence contributes: purpose, requirement, argument list, return value, and caveat. The most important information is front-loaded, and there is no redundant or filler text.
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 tool with annotations covering idempotence and no output schema, the description covers the return value, failure mode, and required permission. Nothing an agent needs to know to call it 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?
The input schema already documents the sole parameter form_id with a type, description, and minLength. The description's 'Args: - form_id (string)' adds no additional meaning beyond what the schema provides. With 100% schema coverage, the baseline 3 is appropriate.
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: 'Publish a form so it's live at its public URL and can accept responses.' This clearly states what the tool does and distinguishes it from siblings like get_form, update_form, and unpublish_form by describing the exact outcome.
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 implies when to use it: when a form should become live and accept responses. It also adds a precondition ('Requires a WRITE-scoped API key') and a caveat about plan limits on Free accounts. However, it does not explicitly name alternatives or state when not to use it, so it misses the full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
foxform_unpublish_formUnpublish a formAUnpublish 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?
The description discloses key behavioral details beyond the annotations: the operation requires a WRITE-scoped API key and the effect of taking the form offline. This aligns with readOnlyHint=false and adds practical context that annotations alone do not provide.
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 short, front-loaded with the action and effect, and includes only essential supporting information: auth requirement, argument list, and return type. Every sentence earns its place.
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 a single required parameter, clear annotations, and no nested schema complexity, the description fully covers what an agent needs: the action, effect, auth requirement, parameter, and return value. Nothing critical 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 description coverage is 100%, and the only parameter, form_id, is already documented in the schema as 'Form ID'. The description merely restates the parameter name without adding extra meaning, so the baseline score of 3 applies.
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 action (unpublish), the resource (form), and the intended effect (takes it offline; stops accepting responses). This meaningfully differentiates it from sibling tools like foxform_publish_form, though it does not explicitly name the alternative.
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 for when to use the tool: when a form should stop accepting responses. It also notes the WRITE-scoped key requirement, which helps the agent determine prerequisites, but it does not explicitly contrast with publish/update or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
foxform_update_formUpdate a FoxForm formAInspectUpdate 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?
The description goes far beyond the annotations by disclosing partial-update semantics, full replacement of questions, validation rejection, warnings for unresolved variables, legacy logic migration, and detailed conditional-navigation behavior. It also states the authentication requirement, which is not in the annotations. There is no contradiction with readOnlyHint=false or idempotentHint=false.
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 well-structured, with an Args section, return value, validation notes, and a dedicated CONDITIONAL LOGIC section. It is front-loaded with the most important behavioral facts. Some minor redundancy exists around unknown fields being rejected, mentioned both before and after the conditional logic section, but every part contributes to correct invocation of a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers parameters, return shape, validation rules, operator alternatives, expression syntax, display logic, auto-advance, legacy behavior, and error-prone edge cases. An agent has enough information to construct valid update payloads and avoid common failure modes.
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 only 33%, but the description compensates fully by explaining every parameter in the Args block. The questions parameter receives especially rich semantics: it replaces the FULL screen list, has no per-screen patch, and includes detailed structure for conditional logic. It also adds meaning to theme, title, description, and thank_you_message beyond their raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Update an existing form's fields, including each screen's conditional logic (branching).' This clearly identifies the tool's action and distinguishes it from create/get/export/list/publish/unpublish siblings. The requirement of a WRITE-scoped API key further clarifies the operation type.
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 for use: updating an existing form, requiring a WRITE-scoped key, and only changing passed fields. It also explicitly routes to foxform_get_form for partial edits ('To add logic to one screen: call foxform_get_form...'). It does not explicitly contrast with foxform_create_form, but 'existing form' plus sibling names make the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
