Skip to main content
Glama

Define a form / order block

set_form
Idempotent

Attach a form viewers can fill in (sign-ups, orders, bookings, leads) to a page: you only define the fields; the platform renders the form in the reading page (mobile-friendly, validated), and each submission lands as a row in this data table, readable with list_data_rows. No form code needed (a plain posting to ./_data/ works too). Idempotent: creates the table when absent, otherwise replaces the whole field definition (rows already collected are kept). fields: at most 20 items of { key, label, type, required?, options?, min?, max?, visibility?, fence? … }; nine types: text (single line), textarea, select (options), multiselect (options, stored joined with 、), number (min / max), phone (11-digit mobile), email, image (check-in photos / collected material; max = how many images, 1–9, default 1; visibility = author — only you and the submitter see the images (default) — or all — shown with the row to every reader, for a check-in wall; viewers pick photos on their phone, the platform compresses them, strips location metadata and runs image moderation, and a row with a flagged image is visible only to you; list_data_rows gives each image a one-hour URL under images), location (location check-in; at most one per table; fence = { lat, lng, radius_m, name? } sets the check-in point, coordinates in GCJ-02 (as picked on Tencent / Amap maps), radius 20–5000 m; without fence there is no range limit and the field just records where viewers checked in (they pick a nearby place and the field stores its name); max_accuracy_m is the accuracy requirement, default 100 m (1000 without fence); out_of_range = reject — out-of-range check-ins are refused (default) — or hold — kept for you to confirm; window = { start, end } is the check-in time window; require_identity defaults to true, meaning viewers check in with their WeChat identity and the table first needs set_data identity=wechat. The page calls space.location({ table }) to get a ticket, puts it in this field and then appends; the row stores the distance in metres plus _loc_in_range / _loc_accuracy_m / _loc_source, never the coordinates; if you really need coordinates pass keep_coords=true — they then appear only to you under location in list_data_rows and are cleared automatically after 30 days). amount is optional and only displays a price: { unit_price_cents, qty_field? (which number field holds the quantity) }; the platform computes the total as unit price × quantity and writes it into each row as _amount_cents — no money is collected (payment guidance and real payment are separate tools). Each row also carries _form_rev (the table version at submission time). Viewer write-back is open by default (append_open=true); pass false to close it. Submissions remain rate-limited and text is moderated first: approved rows appear for viewers on refresh, flagged rows are visible only to you in list_data_rows. Preview and presenter sessions never submit; the author and other workspace members can submit on the live page while signed in, and their rows record which member (by) without counting as a visitor. With members_only=true only members can submit and visitors do not see the form. Page read-back, withdrawal and unknown-column warnings work as described under set_data (_row_id / _at / _status / _mine / _by). Optional notify_emails sends an email for every new approved submission (up to 3 addresses; each new address first gets a confirmation email and only receives notifications after confirming; with an email field, replying reaches the submitter). Share the page after defining the form; the page does not need republishing.

Input Schema

NameRequiredDescriptionDefault
tableYes表名,例如 signup、orders;提交的行落在这张表
titleNo表单标题,也是查看页里那枚按钮的字,例如「报名」「下单」;缺省「填写」
amountNo显示金额;不传 = 不显示金额
fieldsYes字段定义,按顺序渲染
revisionNo可选:get_data 返回的当前 revision,传了就防并发(不一致 409);不传按当前修订写
append_openNo读者写回开关,缺省 true;false = 表单不显示、提交被拒
proposal_idYes
members_onlyNoAccept submissions from workspace members only (visitors do not see the form and get 403); omitted = keep the current value, false for a new table
notify_emailsNo新提交邮件通知:最多 3 个收件邮箱,读者每交一行(过审)发一封邮件给它们,附全部字段;新地址先收确认信、点确认后才发;[] = 不再通知。可单独传

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / fields / items / properties / fence
      Added value: +{
      +  "description": "location:打卡点(GCJ-02 坐标)与半径(米,20–5000)",
      +  "properties": {
      +    "lat": {
      +      "type": "number"
      +    },
      +    "lng": {
      +      "type": "number"
      +    },
      +    "name": {
      +      "maxLength": 40,
      +      "type": "string"
      +    },
      +    "radius_m": {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "lat",
      +    "lng",
      +    "radius_m"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / fields / items / properties / keep_coords
      Added value: +{
      +  "description": "location:是否保存读者的打卡坐标(缺省 false 只存距离);true 时坐标只在 list_data_rows 的 location 里给你看,打卡 30 天后自动清除",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / fields / items / properties / max_accuracy_m
      Added value: +{
      +  "description": "location:定位精度要求(米,10–1000,缺省 100)",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / fields / items / properties / out_of_range
      Added value: +{
      +  "description": "location:超出范围 reject 不收(缺省)/ hold 先收下待你确认",
      +  "enum": [
      +    "reject",
      +    "hold"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / fields / items / properties / require_identity
      Added value: +{
      +  "description": "location:是否要求读者用微信身份(缺省 true)",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / fields / items / properties / type / description
      Previous value: -"text / textarea / select / multiselect / number / phone / email / image"New value: +"text / textarea / select / multiselect / number / phone / email / image / location"
    • changedInput schema / properties / fields / items / properties / type / enum
      Previous value: -[
      -  "text",
      -  "textarea",
      -  "select",
      -  "multiselect",
      -  "number",
      -  "phone",
      -  "email",
      -  "image"
      -]New value: +[
      +  "text",
      +  "textarea",
      +  "select",
      +  "multiselect",
      +  "number",
      +  "phone",
      +  "email",
      +  "image",
      +  "location"
      +]
    • addedInput schema / properties / fields / items / properties / window
      Added value: +{
      +  "description": "location:打卡时间段,带时区的 ISO 时刻",
      +  "properties": {
      +    "end": {
      +      "type": "string"
      +    },
      +    "start": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "start",
      +    "end"
      +  ],
      +  "type": "object"
      +}
  2. Changed4 schema fields changed
    • changedInput schema / properties / fields / items / properties / max / description
      Previous value: -"text / textarea:字数上限(≤ 500);number:上限"New value: +"text / textarea:字数上限(≤ 500);number:上限;image:最多几张(1–9,缺省 1)"
    • changedInput schema / properties / fields / items / properties / type / description
      Previous value: -"text / textarea / select / multiselect / number / phone / email"New value: +"text / textarea / select / multiselect / number / phone / email / image"
    • changedInput schema / properties / fields / items / properties / type / enum
      Previous value: -[
      -  "text",
      -  "textarea",
      -  "select",
      -  "multiselect",
      -  "number",
      -  "phone",
      -  "email"
      -]New value: +[
      +  "text",
      +  "textarea",
      +  "select",
      +  "multiselect",
      +  "number",
      +  "phone",
      +  "email",
      +  "image"
      +]
    • addedInput schema / properties / fields / items / properties / visibility
      Added value: +{
      +  "description": "image:图给谁看 —— author 只有你和提交者本人(缺省);all 跟着这一行给所有读者看(打卡墙)",
      +  "enum": [
      +    "author",
      +    "all"
      +  ],
      +  "type": "string"
      +}
  3. Changed3 schema fields changed
    • changedInput schema / properties / fields / items / properties / type / description
      Previous value: -"text / textarea / select / multiselect / number / phone"New value: +"text / textarea / select / multiselect / number / phone / email"
    • changedInput schema / properties / fields / items / properties / type / enum
      Previous value: -[
      -  "text",
      -  "textarea",
      -  "select",
      -  "multiselect",
      -  "number",
      -  "phone"
      -]New value: +[
      +  "text",
      +  "textarea",
      +  "select",
      +  "multiselect",
      +  "number",
      +  "phone",
      +  "email"
      +]
    • addedInput schema / properties / notify_emails
      Added value: +{
      +  "description": "新提交邮件通知:最多 3 个收件邮箱,读者每交一行(过审)发一封邮件给它们,附全部字段;新地址先收确认信、点确认后才发;[] = 不再通知。可单独传",
      +  "items": {
      +    "maxLength": 254,
      +    "minLength": 3,
      +    "type": "string"
      +  },
      +  "maxItems": 3,
      +  "type": "array"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / members_only
      Added value: +{
      +  "description": "Accept submissions from workspace members only (visitors do not see the form and get 403); omitted = keep the current value, false for a new table",
      +  "type": "boolean"
      +}
  5. First observed

TDQS

A4.5/5.0
Behavior5/5

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

The description adds extensive behavior beyond the annotations: table creation/replacement semantics, rate limiting, moderation, preview/presenter restrictions, member submission recording, image processing, location rules, and notification confirmation flow. These details help the agent predict side effects even though idempotentHint and destructiveHint are already present.

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

Conciseness3/5

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

The purpose is front-loaded, but the description is a very long dense paragraph with some repetition, such as flagged-row visibility and moderation behavior appearing more than once. The detail is mostly relevant for this complex tool, but the structure could be easier to scan with shorter grouping.

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?

Given the complex nested field schema, nine parameters, and no output schema, the description covers the essential behavior an agent needs: form definition, field types, identity requirements, submission moderation, notifications, and how to read submissions via list_data_rows. It points to set_data for shared read-back/withdrawal semantics, which fills the remaining context.

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 high at 89%, and the description still adds substantial meaning for fields, amount, append_open, members_only, notify_emails, and the image/location field types. It does not explain proposal_id or revision in prose, though revision is described in the schema and proposal_id appears to be a generic required identifier.

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 description uses a specific verb and resource: it defines a form/order block with fields attached to a page, and submissions land as rows. It explicitly names related tools such as list_data_rows and set_data, so an agent can distinguish its role from plain data-table operations.

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

Usage Guidelines4/5

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

It gives clear usage context: define the form, share the page, and no republishing is needed; it also notes that payment and payment guidance are separate tools. It lacks an explicit comparison such as 'use set_data instead when you only need a table without a form', but the surrounding guidance is strong.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources