List forms/projects (surveys) accessible with the configured API token.

Does NOT return submission data — use kobo_list_submissions for that.

Args:

• search (string, optional): filter forms whose name contains this text

• limit (number): max forms to return, 1-100 (default 30)

• offset (number): pagination offset (default 0)

• response_format ('markdown' | 'json')

Returns: form uid, name, deployment status, and submission count for each form.

Examples:

• Use when: "What forms do I have on Kobo?" -> no params

• Use when: "Find my cocoa tracking form" -> search="cocoa"

Get full details of a single form: its question structure, section nesting, skip logic and validation rules.

Args:

• uid (string): the form's asset uid (from kobo_list_forms)

• language (string, optional): which language's labels to show on a multilingual form (e.g. 'fr')

• response_format ('markdown' | 'json')

Returns: name, deployment status, submission count, available languages, and the question outline — groups and repeats shown as indented sections, with required, skip logic and constraints annotated.

Error Handling:

• Returns "Error: ... not found" if the uid doesn't exist or isn't accessible with this token

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.

Replace the ENTIRE question list of an existing form with a new one.

Prefer kobo_patch_form for targeted edits (relabelling, adding choices, changing skip logic) — it leaves the rest of the form untouched and cannot accidentally drop questions.

Args:

• uid (string): asset uid of the form to update

• questions (array): FULL replacement list — any question left out is REMOVED from the form

• redeploy (boolean, default true): redeploy so the new version goes live

• confirm_replace (boolean): must be true when the form already has submissions

Notes:

• Existing submissions are preserved, but answers to removed questions become orphaned and stop appearing in exports.

• The question list is validated locally before anything is sent to Kobo.

Make targeted changes to an existing form without resending the whole question list.

This is the safe way to fix a typo, add a choice, or attach skip logic to a form that is already collecting data — everything not named is left exactly as it is.

Args (all optional, combine freely):

• uid (string): the form to patch

• set_label: [{name, label}] — relabel existing questions

• set_hint: [{name, hint}]

• set_required: [{name, required}]

• set_relevant: [{name, relevant}] — set skip logic; empty string clears it

• set_constraint: [{name, constraint, constraint_message}] — empty constraint clears it

• add_choices: [{name, choices:[{name,label}]}] — append options to a select question

• remove_questions: [names] — delete questions; removing a group removes its contents

• redeploy (boolean, default true)

Returns: a per-change report of what was applied and what could not be found.

Examples:

• Fix one label: set_label=[{name:"nom_etablissement", label:"Nom de l'établissement"}]

• Add skip logic after the fact: set_relevant=[{name:"type_autre", relevant:"${type} = 'autre'"}]

• Add a payment option: add_choices=[{name:"moyens_paiement", choices:[{name:"wave",label:"Wave"}]}]

Deploy a draft form (or redeploy a changed one) so it becomes active and can collect submissions.

Args:

• uid (string): asset uid of the form to deploy

Returns: the new deployment status and the collect links.

Note: deploying makes the form live but NOT public — the Enketo link still asks for a Kobo login until anonymous submissions are enabled with kobo_set_sharing.

Stop a form from accepting new submissions without deleting anything, or bring an archived form back.

This is the correct way to end a data collection round: every response is kept and stays exportable. Use it instead of kobo_delete_form, which destroys the data.

Args:

• uid (string): asset uid of the deployed form

• active (boolean): false to archive, true to reactivate

Returns: the resulting deployment status.

Copy an existing form's structure into a brand-new project, without its submissions.

Useful to reuse a questionnaire for a new round, region or season, or to experiment on a copy instead of a live form.

Args:

• uid (string): asset uid of the form to copy

• name (string, optional): name for the copy (default ' (copie)')

• deploy (boolean, default false): deploy the copy immediately

Returns: the new form's uid and status.

Download a form as a real XLSForm .xlsx workbook — the standard exchange format for ODK/Kobo questionnaires.

Use it to hand the questionnaire to someone else, keep it under version control, edit it in Excel, or re-import it elsewhere with kobo_import_xlsform.

Args:

• uid (string): asset uid of the form

• output_path (string, optional): where to write the file

Returns: the path written and its size.

Upload an XLSForm .xlsx workbook to Kobo, either as a new form or to overwrite an existing one.

Use it when a questionnaire already exists as a spreadsheet, or to round-trip a form edited in Excel.

Args:

• file_path (string): path to the .xlsx on disk

• name (string, optional): name for the imported form

• uid (string, optional): asset uid to overwrite; omit to create a new form

• deploy (boolean, default false): deploy once the import finishes

Returns: the resulting form uid and import status.

Error Handling:

• Kobo validates the workbook server-side; a malformed XLSForm comes back with the specific row/column it rejected.

Permanently delete a form AND ALL ITS SUBMISSIONS. THIS CANNOT BE UNDONE.

Args:

• uid (string): asset uid of the form to delete

• confirm (true): must be explicitly set to true

• confirm_submission_count (number): required when the form has submissions — pass the exact count, to prove the data loss is intended

Don't use when: you just want to stop collecting data. Use kobo_archive_form instead — it keeps every response.

List a form's deployed versions, and roll back to one of them.

Kobo keeps every version that was ever deployed. This is the way back when a change breaks a live form: redeploying a past version restores the old structure without touching the submissions already collected.

Args:

• uid (string): asset uid of the form

• rollback_to (string, optional): version uid to redeploy. Omit to only list the history.

• limit (number, default 30): how many versions to list

• response_format ('markdown' | 'json')

Returns: the version history (newest first) with deployment dates, and the resulting status after a rollback.

Notes:

• Rolling back changes the form structure only. Answers collected under the newer version stay in the database, but fields that no longer exist drop out of exports.

Get the shareable links of a deployed form — the actual deliverable once a form is built.

Returns every Enketo URL Kobo publishes:

• offline: caches in the browser and works without a connection, syncing later. The one to give field teams.

• online: plain web form

• single: submits once and closes, for one-response-per-person links

• preview: renders the form without saving anything, for internal review

• iframe: to embed the form in a web page

It also reports whether the form is genuinely PUBLIC. A deployed form's link still asks for a Kobo login until anonymous submissions are enabled — use kobo_set_sharing for that.

Args:

• uid (string): asset uid of the deployed form

• include_qr (boolean, default false): also return a QR code image of the offline link, to print on a flyer, a poster or a table card

• response_format ('markdown' | 'json')

Control who can fill in a form and who can work on it.

Two independent things:

• anonymous_submissions: makes the collect link usable by ANYONE who has it, with no Kobo account. This is what turns a deployed form into a genuinely public link. It never lets the public read the responses already collected — only submit new ones.

• share_with / revoke_from: give or remove named collaborators' access to the form and its data.

Roles:

• view: see the form and read its submissions

• edit: also add and change submissions, and edit the form

• manage: full control, including sharing it further

Args:

• uid (string): asset uid of the form

• anonymous_submissions (boolean, optional): true to publish, false to revoke

• share_with: [{username, role}]

• revoke_from: [usernames] — removes every permission that user holds

• response_format ('markdown' | 'json')

Returns: the resulting access list, and the collect links when the form becomes public.

Examples:

• "Make my form publicly fillable" -> anonymous_submissions=true

• "Let Awa edit the data" -> share_with=[{username:"awa", role:"edit"}]

Notes:

• Publishing a form is outward-facing: anyone with the URL can then submit. Confirm with the user before enabling it unless they asked.

List submitted responses for a form, most recent first.

Args:

• uid (string): the form's asset uid (from kobo_list_forms)

• limit (number): max submissions to return, 1-100 (default 30)

• offset (number): pagination offset (default 0)

• query (string, optional): Mongo-style JSON filter, e.g. '{"crop_health":"poor"}'

• response_format ('markdown' | 'json')

Returns: submission id, submission time, and answered fields for each submission.

Examples:

• Use when: "Show me the latest 10 responses to my cocoa form" -> uid=..., limit=10

• Use when: "Which submissions reported poor crop health?" -> query='{"crop_health":"poor"}'

• Don't use when: you want a downloadable Excel file (use kobo_export_submissions_excel instead)

Get the full detail of one submission by its id.

Args:

• uid (string): the form's asset uid

• submission_id (string): the submission id (the "_id" field from kobo_list_submissions)

• response_format ('markdown' | 'json')

Returns: every field and value recorded in that submission.

Permanently delete specific submissions from a form. THIS CANNOT BE UNDONE.

Use it to remove test entries, duplicates, or a response a respondent asked to withdraw.

Args:

• uid (string): asset uid of the form

• submission_ids (array of strings): the "_id" values from kobo_list_submissions

• confirm (true): must be explicitly set to true

Don't use when: you want to discard a whole form's data — that is kobo_delete_form. To merely flag bad rows while keeping them, use kobo_validate_submissions with 'not approved' instead.

Mark submissions as approved, not approved, or on hold — Kobo's data-cleaning workflow.

This is the non-destructive way to handle suspect responses: the row stays in the database and in exports, carrying its status, instead of being deleted.

Args:

• uid (string): asset uid of the form

• submission_ids (array of strings): the "_id" values to mark

• status: 'validation_status_approved' | 'validation_status_not_approved' | 'validation_status_on_hold'

Returns: how many submissions were updated.

Download the photos, audio, video and files attached to submissions.

A form with an 'image' question (a shopfront photo, a signed consent form, a damaged crop) stores its files on Kobo, and nothing in an Excel export contains them — only file names. This fetches the actual files to disk, organised one folder per submission.

Args:

• uid (string): asset uid of the form

• submission_ids (array, optional): limit to these submissions; omit for all

• output_dir (string, optional): where to write (default: /_attachments)

• max_files (number, default 200): safety cap

Returns: the directory written, the number of files and their total size.

Send a response to a deployed form through the API, without going through the web form.

Use it to test a form end-to-end before sending enumerators out, or to migrate answers already collected on paper or in a spreadsheet.

Args:

• uid (string): asset uid of the DEPLOYED form

• answers (object): values keyed by the question's submission path, exactly as kobo_get_form reports it. A question inside a group is "group_name/question_name". select_multiple values are space-separated codes: "especes mobile_money". Dates are ISO: "2026-09-16". geopoint is "lat lon altitude accuracy".

• count (number, default 1): submit the same answers several times, for load-testing only

Returns: the instance id Kobo assigned.

Notes:

• Submitted rows are real data and count towards the form's submission total. Delete test rows with kobo_delete_submissions.

• Attachments (photos, audio) cannot be sent this way — use the web form for those.

Error Handling:

• A rejected submission almost always means a field name that does not exist in the form; check the exact paths with kobo_get_form.

Generate a downloadable Excel (.xlsx) or CSV export of all submissions for a form, and return the file itself (base64-encoded) plus a direct download link.

This triggers a fresh export on the Kobo server, waits (up to ~90s) for it to finish, downloads the result, and returns it as an embedded file the calling app can save to disk.

Args:

• uid (string): the form's asset uid (from kobo_list_forms)

• format ('xlsx' | 'csv', default 'xlsx')

• language (string, optional): label language for the column headers on a multilingual form

Returns: the file as an embedded resource (base64), its size, and a direct download URL as a fallback.

Examples:

• Use when: "Give me an Excel file of all responses to my cocoa form" -> uid=..., format="xlsx"

• Don't use when: you just want to read a few submissions in chat (use kobo_list_submissions instead — much faster)

Error Handling:

• Returns "Error: ... did not complete within 90s" for very large forms — the export may still finish server-side; check the Kobo web UI's export history

Download ALL submissions of a form and prepare them for analysis. Start every analysis here.

Unlike kobo_list_submissions (one page of raw records), this pulls the whole dataset, replaces stored choice codes with their labels, converts numbers and dates, flattens groups, and reports data quality. The cleaned snapshot is cached for 15 minutes and reused by kobo_analyze, kobo_crosstab, kobo_get_data_sample and kobo_build_report.

Args:

• uid (string): the form's asset uid

• query (string, optional): Mongo-style server-side filter, e.g. '{"region":"Sud-Ouest"}'

• max_rows (number): safety cap (default: everything, up to 50000)

• language (string, optional): label language for multilingual forms

• refresh (boolean): re-download instead of using the cache

• response_format ('markdown' | 'json')

Returns: the list of analysable questions with their measurement type (categorical / numeric / datetime / text) and answer options, the number of submissions, and a data-quality summary (missing values, duplicates, skipped repeat groups).

Use the returned question list to decide what to analyse — its "field" values are what you pass to the other tools.

Compute descriptive statistics for every question (or a chosen subset) of a form.

For each question it returns the statistics that fit its type:

• categorical: counts and percentages per answer option (multi-select handled correctly — percentages are of respondents, so they can exceed 100%)

• numeric: n, mean, median, standard deviation, min, max, quartiles, sum

• date: earliest and latest

• free text: number of distinct answers plus examples

Args:

• uid (string): the form's asset uid

• columns (array, optional): restrict to these questions (field name or question label)

• query (string, optional): Mongo-style filter

• response_format ('markdown' | 'json')

Loads the data automatically if it isn't cached yet.

Examples:

• Use when: "What do the responses to my cocoa form look like?" -> uid=...

• Use when: "What's the average plot size?" -> columns=["plot_size"]

• Don't use when: you need two questions crossed (use kobo_crosstab)

Cross two questions to see how answers to one vary with the other — the core of comparative analysis.

Args:

• uid (string): the form's asset uid

• row_column (string): question forming the rows (field name or label)

• col_column (string): question forming the columns

• metric: 'count' (default), 'row_pct', 'col_pct', 'mean' or 'sum'

• value_column (string): numeric question to average/sum — required for 'mean' and 'sum'

• query (string, optional): Mongo-style filter

• response_format ('markdown' | 'json')

Returns: the contingency table with row, column and grand totals, and how many submissions were excluded for missing either answer.

Examples:

• Use when: "Is crop health worse in some regions?" -> row_column="region", col_column="crop_health"

• Use when: "Share of each health status within each region" -> ..., metric="row_pct"

• Use when: "Average plot size by region and crop" -> row_column="region", col_column="crop", metric="mean", value_column="plot_size"

Return actual cleaned rows of the dataset, with labels rather than codes.

Use this to read open-ended answers, sanity-check the data before drawing conclusions, or inspect specific records. For aggregate figures prefer kobo_analyze or kobo_crosstab — they are far more compact.

Args:

• uid (string): the form's asset uid

• limit (number): rows to return, 1-200 (default 20)

• offset (number): rows to skip (default 0)

• columns (array, optional): only these questions

• query (string, optional): Mongo-style filter

• response_format ('markdown' | 'json')

Produce finished deliverables from a form's data: an analytical Excel workbook, a written Word report, and/or a PDF — saved to disk.

YOU write the analysis (objective, summary, findings, section commentary, recommendations); the server computes every figure from the real submissions, so the numbers in the deliverable always match the data. Never type counts or percentages into 'custom' tables that the server can compute for you — use the directives below instead.

Each section carries your prose plus 'visuals', declared as directives:

• {source:"frequencies", column:"crop_health", chart_kind:"pie"} — counts/% per answer, as table and chart

• {source:"numeric_summary", column:"plot_size"} — mean/median/std/quartiles table

• {source:"crosstab", row_column:"region", col_column:"crop_health", metric:"count"} — contingency table + grouped chart

• {source:"custom", columns:[...], rows:[[...]]} — only for figures the server cannot derive Each accepts: show ('table'|'chart'|'both'), chart_kind, title, note (a "how to read this" caption), top_n.

What the Excel workbook contains: a summary sheet (objective, executive summary, findings, recommendations), one sheet per section with tables and NATIVE, editable Excel charts, a cross-tab sheet, the cleaned data as a real Excel Table named 'DonneesKobo' (select it, then Insert > PivotTable to build your own pivot in two clicks), and a data-quality sheet.

Note on pivot tables: cross-tabs are delivered as computed tables, not as live PivotTable objects — no open-source library can create those. The named Excel Table above is there precisely so you can add one yourself instantly.

Args:

• uid (string): the form's asset uid

• objective (string): the analytical question this report answers

• formats (array): any of 'xlsx', 'docx', 'pdf'

• title, methodology, summary, findings[], recommendations[]: your written content

• sections[]: {heading, text, visuals[]}

• file_name (string, optional): base name without extension

• query (string, optional): Mongo-style filter restricting the analysis

Returns: the full path of each generated file.

Run kobo_load_data first so you know which questions exist and what shape the data is in.

Diagnose this server's configuration: the Kobo connection, the API token, the output directory and the Python report renderer.

Run it first when a tool fails for an unclear reason, or right after installing the server.

Returns: a pass/fail line per check, with the exact command to fix anything broken.