Skip to main content
Glama
OuattaraTech

kobotoolbox-mcp-server

by OuattaraTech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Create KoboToolbox Form

kobo_create_form

Create a survey form from a flat question list, including sections, skip logic, and local validation, then deploy it to start collecting submissions.

Instructions

Create a new form (survey) from a list of questions, and optionally deploy it immediately so it can start collecting submissions.

The question list is FLAT: sections and repeats are expressed with begin_group/end_group and begin_repeat/end_repeat rows, which must be balanced.

Args:

  • name (string): form/project title

  • description (string, optional): short description

  • questions (array): ordered list of questions. Each has:

    • type: see the type enum. Use 'phonenumber' (NOT 'phone_number') for a phone field.

    • name: internal field name, unique across the whole form

    • label: question text (string, or {language: text} for a multilingual form)

    • required, hint, choices, relevant, constraint, constraint_message, calculation, default, appearance, read_only, parameters

  • deploy (boolean, default true): deploy immediately vs. leave as draft

Returns: the new form's uid, deployment status, and — once deployed — the public collect links.

Examples:

  • Sections and skip logic: questions=[ {type:"begin_group",name:"identification",label:"Identification",appearance:"field-list"}, {type:"text",name:"nom",label:"Nom de l'établissement",required:true}, {type:"select_one",name:"categorie",label:"Catégorie",choices:[{name:"maquis",label:"Maquis"},{name:"autre",label:"Autre"}]}, {type:"text",name:"categorie_autre",label:"Précisez",relevant:"${categorie} = 'autre'"}, {type:"integer",name:"annee",label:"Année",constraint:". >= 1950 and . <= 2030",constraint_message:"Année invalide"}, {type:"end_group",name:"identification"} ]

  • Repeating data: begin_repeat "plats" ... end_repeat, one row per dish.

  • Don't use when: you want to change an existing form (use kobo_patch_form for a targeted edit, kobo_update_form to replace everything)

Error Handling:

  • The question list is validated locally first: unknown types, duplicate names, unbalanced groups, selects without choices and bad choice codes are reported precisely, before any request reaches Kobo.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesTitle of the form/project (e.g. 'Suivi des parcelles de cacao')
deployNoIf true, immediately deploy the form so it can start collecting submissions
questionsYesOrdered, flat list of questions. Nesting is expressed with begin_group/end_group and begin_repeat/end_repeat rows, which must be balanced.
descriptionNoOptional short description of the form's purpose

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already mark the operation as non-read-only and non-idempotent, and the description adds concrete behavioral context: creating versus deploying, the flat-list balance requirement, local validation before any request reaches Kobo, and the return value (uid, deployment status, public collect links). No annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: purpose, flat-list warning, condensed args, return values, concrete examples, explicit alternative routing, and error handling. It is front-loaded with the core action and uses headers and lists so an agent can scan it quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex form-creation tool with no output schema, the description provides the essential missing pieces: return shape, deployment behavior, local validation semantics, and representative usage. The rich input schema handles the per-field details, and the description fills the operational context around it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries most parameter definitions; the description adds value by showing complete question examples (grouping, relevant skip logic, constraint messages, repeat rows), the multilingual label form, and the explicit phonenumber spelling warning. This goes beyond a bare schema listing, though it does repeat several schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific action ('Create a new form (survey)') on a specific resource, with a precise input ('from a list of questions') and an optional behavioral toggle ('optionally deploy it immediately'). It later explicitly routes edits to kobo_patch_form and kobo_update_form, so it is clearly distinguished from the update siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit 'Don't use when' section: if the goal is to change an existing form, use kobo_patch_form for targeted edits or kobo_update_form to replace everything. It also clarifies the deploy flag choice between immediate collection and leaving a draft, giving the agent a clear decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools