Skip to main content
Glama

create_block

Create a new block on a page. Block types and their props:

  • text: Rich markdown content. Props: {"content": "markdown text"}

  • checklist: Task list with checkboxes. Props: {"items": [{"id": "item-0", "text": "Task", "done": false}]} or use add_checklist_item after creation

  • ctlsurf_task: Agent task assignments with notes. Props: {"items": [{"id": "task-0", "text": "Task", "done": false, "notes": []}]} or use add_ctlsurf_task_item after creation

  • table: Structured data grid. Props: {"columns": ["Col1", "Col2"], "rows": [["val1", "val2"]]}

  • tree: Hierarchical tree display. Props: {"nodes": [{"id": "1", "label": "Root", "children": [{"id": "2", "label": "Child"}]}]}

  • react_flow: Interactive node graph (auto-creates Graph). Props: {"graph_id": "uuid"} or empty to auto-create

  • page_summary: Page metadata for organization. Props: {"summary": "...", "purpose": "...", "status": "active", "tags": [], "key_topics": []}

  • file: File/image attachment. Props: {"file_id": "uuid", "filename": "name.ext", "mime_type": "image/png", "size_bytes": 12345}. To upload, use get_upload_url + curl PUT + confirm_upload — this creates the file block for you.

  • mindmap: Interactive mind map with visual editor. Props: {"content": "..."} where content can be:

    Option 1 - Markdown format (recommended for agents):

    # Central Topic
    ## Branch 1
    - Leaf item A
    - Leaf item B
    ## Branch 2
    ### Sub-branch
    - [[Linked Page|page-uuid]]

    Use # for root, ## for branches, ### for sub-branches, - for leaf items. Link to pages with [[Display Text|page-uuid]] syntax.

    Option 2 - JSON tree format:

    {"id": "root", "text": "Central Topic", "children": [
      {"id": "b1", "text": "Branch 1", "children": [
        {"id": "l1", "text": "Leaf", "children": [], "link": "/page/uuid"}
      ]}
    ]}

Dataspace blocks (dataspace pages only — use dedicated tools instead of create_block):

  • datastore: (dataspace pages only) Structured data table with typed columns and row-level operations. Use create_datastore tool instead.

  • state: (dataspace pages only) Key-value store for agent config, counters, flags. Props: {"data": {"key": "value"}}. Use get_state/set_state tools.

  • log: (dataspace pages only) Append-only timestamped event stream. Props: {"entries": [], "max_entries": 1000}. Use append_log/query_log tools.

These block types can ONLY be created on pages with type="dataspace" (e.g., the "Agent Datastore" page under your project root).

  • presentation: Slide deck (960x540 canvas, .pptx export). Use the create_presentation tool, then add_slide_from_template / add_structured_slide for rich structured slides. Markdown content slides render as flat text (no tables/bold/links) — avoid for real decks. Props: {"slides": [...], "config": {"theme": "dark"}}.

  • swimlane: Project timeline: tasks in lanes with start/due dates, progress, status and dependencies, shown with a today line and overdue flags. Use load_toolset(toolset="swimlanes") then create_swimlane / add_swimlane_task; tasks are not stored in props.

  • visual: Explanatory graphic (steps, flow, compare, stats, bars, callout, tokens, cycle, funnel). Prefer it over long lists when explaining; use load_toolset(toolset="visuals") then create_visual.

Use checklist for simple task lists, ctlsurf_task for agent-assigned work with progress notes.

Tickets are not blocks: to create a ticket use create_ticket. Agents cannot add text, checklist, task or other non-dataspace blocks to a project's Tickets page.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "page_id": "<page_id>",
      "type": "<type>"
    },
    "name": "create_block"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeYesBlock type: text (markdown), checklist (tasks), table (grid data), tree (hierarchy), react_flow (node graph), ctlsurf_task (agent tasks), page_summary (page metadata), file (attachments/images), mindmap (interactive mind map), datastore (structured table - prefer create_datastore tool), state (key-value store), log (event stream), presentation (slide deck - prefer create_presentation tool), swimlane (project timeline - prefer create_swimlane tool), visual (explanatory graphic - prefer create_visual tool)
propsNoBlock-specific properties (see tool description for each type's props structure)
titleNoOptional title/header for the block
page_idYesThe UUID of the page

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / type / description
      Previous value: -"Block type: text (markdown), checklist (tasks), table (grid data), tree (hierarchy), react_flow (node graph), ctlsurf_task (agent tasks), page_summary (page metadata), file (attachments/images), mindmap (interactive mind map), datastore (structured table - prefer create_datastore tool), state (key-value store), log (event stream), presentation (slide deck - prefer create_presentation tool), swimlane (project timeline - prefer create_swimlane tool)"New value: +"Block type: text (markdown), checklist (tasks), table (grid data), tree (hierarchy), react_flow (node graph), ctlsurf_task (agent tasks), page_summary (page metadata), file (attachments/images), mindmap (interactive mind map), datastore (structured table - prefer create_datastore tool), state (key-value store), log (event stream), presentation (slide deck - prefer create_presentation tool), swimlane (project timeline - prefer create_swimlane tool), visual (explanatory graphic - prefer create_visual tool)"
    • changedInput schema / properties / type / enum
      Previous value: -[
      -  "text",
      -  "checklist",
      -  "table",
      -  "tree",
      -  "react_flow",
      -  "ctlsurf_task",
      -  "page_summary",
      -  "file",
      -  "mindmap",
      -  "datastore",
      -  "state",
      -  "log",
      -  "presentation",
      -  "swimlane"
      -]New value: +[
      +  "text",
      +  "checklist",
      +  "table",
      +  "tree",
      +  "react_flow",
      +  "ctlsurf_task",
      +  "page_summary",
      +  "file",
      +  "mindmap",
      +  "datastore",
      +  "state",
      +  "log",
      +  "presentation",
      +  "swimlane",
      +  "visual"
      +]
  2. Changed2 schema fields changed
    • changedInput schema / properties / type / description
      Previous value: -"Block type: text (markdown), checklist (tasks), table (grid data), tree (hierarchy), react_flow (node graph), ctlsurf_task (agent tasks), page_summary (page metadata), file (attachments/images), mindmap (interactive mind map), datastore (structured table - prefer create_datastore tool), state (key-value store), log (event stream), presentation (slide deck - prefer create_presentation tool)"New value: +"Block type: text (markdown), checklist (tasks), table (grid data), tree (hierarchy), react_flow (node graph), ctlsurf_task (agent tasks), page_summary (page metadata), file (attachments/images), mindmap (interactive mind map), datastore (structured table - prefer create_datastore tool), state (key-value store), log (event stream), presentation (slide deck - prefer create_presentation tool), swimlane (project timeline - prefer create_swimlane tool)"
    • changedInput schema / properties / type / enum
      Previous value: -[
      -  "text",
      -  "checklist",
      -  "table",
      -  "tree",
      -  "react_flow",
      -  "ctlsurf_task",
      -  "page_summary",
      -  "file",
      -  "mindmap",
      -  "datastore",
      -  "state",
      -  "log",
      -  "presentation"
      -]New value: +[
      +  "text",
      +  "checklist",
      +  "table",
      +  "tree",
      +  "react_flow",
      +  "ctlsurf_task",
      +  "page_summary",
      +  "file",
      +  "mindmap",
      +  "datastore",
      +  "state",
      +  "log",
      +  "presentation",
      +  "swimlane"
      +]
  3. First observed

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are supplied, so the description carries the full burden and delivers substantial context: dataspace blocks can only be created on type="dataspace" pages, react_flow "auto-creates Graph", file uploads go through get_upload_url + curl PUT + confirm_upload and the block is created for you, presentation markdown content slides render as flat text, and swimlane tasks are "not stored in props". Missing: where the block lands on the page (ordering/position), permission requirements, and whether repeated calls create duplicates.

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?

Long but structured: a one-line purpose statement up front, then bolded type headings with inline props examples, then a clearly separated dataspace/advanced section. Some duplication with the enum descriptions in the schema ("prefer create_datastore tool" appears in both places), which costs a little, but nearly every line earns its place for a polymorphic tool.

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?

For a mutation tool with zero annotations and no output schema, the description covers types, cross-tool routing, and dataspace restrictions well. The notable gap is return behavior — an agent likely needs the created block's id for update_block/delete_block/get_block_history, and nothing here says what comes back or how to obtain the id.

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%, but the props parameter's schema description only defers to the tool description, so the per-type props documentation (checklist items shape, table columns/rows, tree nodes, mindmap markdown vs JSON, page_summary fields, file metadata) is genuine added meaning. Not fully complete: datastore props are absent, log entries are only sketched, and the title parameter gets no elaboration.

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?

Opens with a specific verb+resource ("Create a new block on a page") and immediately enumerates the block types it can create, each with its props shape. An agent can distinguish it from create_datastore, create_swimlane, create_visual, create_presentation and create_ticket because the description explicitly names those siblings and routes them away.

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?

Explicit when-to-use and when-not-to-use guidance: datastore/state/log blocks say "use `create_datastore` tool instead" / "Use `get_state`/`set_state` tools", presentation/swimlane/visual point to load_toolset plus the dedicated creator, and the closing lines state "Tickets are not blocks: to create a ticket use `create_ticket`". It even states an audience restriction ("Agents cannot add ... blocks to a project's Tickets page"), leaving no inference needed.

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