ctlsurf

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"}}.

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

Input Schema

TableJSON Schema

Name	Required	Description
`type`	Yes	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)
`props`	No	Block-specific properties (see tool description for each type's props structure)
`title`	No	Optional title/header for the block
`page_id`	Yes	The UUID of the page

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 24, 2026

TDQS

A4.6/5.0

Behavior4/5

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

No annotations are provided, so the description carries the behavioral burden. It discloses several behavioral traits: react_flow auto-creates a Graph, markdown slide content renders as flat text, file upload through get_upload_url + confirm_upload creates the block, and dataspace blocks are restricted to dataspace pages. It stops short of describing return values, error conditions, or permissions, which is why it is not a 5.

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?

The description is long but front-loaded with purpose and organized by block type with consistent bullet formatting and code examples. Every section earns its place given 13 block types, but the overall length prevents a perfect conciseness score.

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 complex tool with no output schema and no annotations, the description covers all block types, their required props, constraints, and sibling-tool alternatives, which is enough to invoke correctly. The only notable omissions are return value and error behavior, which a brief addendum could close.

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

Parameters5/5

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

Even though schema coverage is 100%, the props parameter remains a generic object and the description supplies the actual prop structures for every block type, with examples for nested mindmap and JSON tree formats. This meaningfully exceeds the schema's enum descriptions and is essential for correct invocation.

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 opens with 'Create a new block on a page,' naming the exact verb and resource, then enumerates all supported block types. It distinguishes the tool from siblings by noting which tools handle checklist item mutation, uploads, dataspace blocks, and presentations.

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?

It gives explicit routing guidance: use add_checklist_item/add_ctlsurf_task_item after creation, use create_datastore/get_state/set_state/append_log/query_log for dataspace-only types, and use create_presentation for slide decks. It also states the dataspace-page-only restriction and the recommendation to prefer checklist for simple tasks versus ctlsurf_task for agent-assigned work.

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

All ctlsurf tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?