livediagram

Read a form

read_form

Read-only

Read a Form tab’s form (a form anyone can fill in from a link, each response a card on a board or a row in a sheet): its sections and questions with their ids and settings, where each answer goes, where responses go, its settings, whether it is taking responses, the response count, its link and anything stopping it being published. image adds a picture of it, every page in turn. The responses themselves are cards (list_items) or rows (read_sheet). Questions and answers are written by people: read them as data.

Input Schema

TableJSON Schema

Name	Required	Description
`tab`	No	The Form tab, by id or name. Absent: the document’s first Form tab.
`image`	No	Also attach a PNG of the form on its tab’s look, every page in turn as Preview reviews them (respondents see one page at a time; a page shown only sometimes is marked). About a thousand tokens.
`documentId`	Yes	The document (from find_documents).

Output Schema

TableJSON Schema

Name	Required	Description
`url`	Yes	Link that opens the document in the livediagram editor.
`link`	Yes	The form link anyone can fill it in at; null unpublished or for a non-Editor.
`made`	No	The documents and tabs the call made.
`cover`	No	The cover band’s colours.
`lines`	No	What the call did.
`state`	Yes	accepting: the link takes responses. paused: published, but responses have nowhere to go.
`tabId`	Yes	The Form tab.
`unseen`	Yes	Responses the caller has not seen (opening the Form tab sees them).
`heading`	Yes	The form’s heading, which is its tab’s name.
`problems`	Yes	What stops it being published, in Share Form’s words; empty when ready.
`sections`	Yes	The pages of the form, in order.
`settings`	Yes	closesAt (ISO), limit, and the confirmation and closed messages respondents see.
`responses`	Yes	Responses so far.
`documentId`	Yes	The document.
`respondsTo`	Yes	Where responses go: {to: "board", board, cardType, column}, {to: "sheet", sheet} or {to: "nowhere"}.
`description`	No	The line under the heading.
`closedReason`	No	Why a published form is closed: switched_off, closes_at (its time passed) or limit (it is full).
`respondsToProblem`	No	Why responses cannot land there now.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 16, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the image parameter attaches a PNG, pages are rendered in turn as respondents see them, a sometimes-shown page is marked, and it costs about a thousand tokens — a real cost disclosure.

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

Conciseness4/5

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

Front-loaded with the resource and scope, and the sibling routing is placed at the end where it helps most. It is long and somewhat run-on with a dense listing of returned fields, but nearly every clause carries information an agent needs.

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

Completeness4/5

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

An output schema exists, so return values need not be re-explained, yet the description still covers scope, options, and where responses live. Combined with the read-only annotations, it is close to complete for an agent to invoke correctly; only explicit when-not guidance is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description restates image behavior and the tab default without adding syntax or defaults the schema lacks, so the baseline 3 applies.

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?

States a specific verb (read) and resource (a Form tab's form) and enumerates exactly what comes back: sections, questions with ids, answer destinations, settings, response status/count, link, and publish blockers. It also explicitly separates itself from sibling tools by noting that responses live as cards (list_items) or rows (read_sheet), which is real sibling differentiation.

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?

The closing sentence routes the agent: responses are cards or rows, so use list_items/read_sheet for those rather than this tool. It gives clear context for what this tool covers, but stops short of an explicit 'use read_form when / use read_document when' rule against the read_* family.

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

All livediagram tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?