Skip to main content
Glama
Sign In

Dock

by ai.trydock
OverviewDiscussionsAdmin

create_surface

Create a new surface inside a workspace. kind picks table, doc, html, files, or video. Optional slug (lowercase kebab-case, 3-64 chars); when omitted the server slugifies name and appends a numeric suffix on collision. Optional columns sets a table's starting columns; without it the table starts EMPTY and your first row write creates the columns its data needs. Ignored for other kinds. html surfaces start with an empty body — write content via update_html. files surfaces start empty; browse them with list_files / get_file / list_recent_files, and add files with upload_file (for a file on your own machine or over ~3 MB, call create_file_upload first). video surfaces hold one or more videos people flip through (variants, cuts): add each with add_video from an https URL (mp4, webm, mov or m4v); for a video on your own machine, get that URL with create_video_upload. Editor role required. Emits surface.created so live listeners on the workspace stream see the new surface without a refetch.

Input Schema

NameRequiredDescriptionDefault
kindYesSurface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML page, `files` for uploaded files + folders (put a local file in with `create_file_upload` then `upload_file`), `video` for a surface of videos people flip through (a local video goes in with `create_video_upload` then `add_video`).
nameYesDisplay name of the surface. 1-64 chars.
slugYesThe workspace slug. Accepts either the bare slug ('my-workspace') or the org-prefixed form ('my-org/my-workspace') as shown in the dashboard URL; both resolve to the same workspace.
columnsNoOptional initial columns for `table` kind. Same shape as get_workspace_schema returns. Omit for an empty table.
surface_slugNoOptional URL-friendly slug for the surface (lowercase kebab-case, 3-64 chars). Auto-derived from `name` when omitted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / columns / description
      Previous value: -"Optional initial columns for `table` kind. Same shape as get_workspace_schema returns. Defaults to Title/Status/Notes when omitted."New value: +"Optional initial columns for `table` kind. Same shape as get_workspace_schema returns. Omit for an empty table."
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders (put a local file in with `create_file_upload` then `upload_file`), `video` for a tab of videos people flip through (a local video goes in with `create_video_upload` then `add_video`)."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML page, `files` for uploaded files + folders (put a local file in with `create_file_upload` then `upload_file`), `video` for a surface of videos people flip through (a local video goes in with `create_video_upload` then `add_video`)."
    • changedInput schema / properties / name / description
      Previous value: -"Display name shown on the tab. 1-64 chars."New value: +"Display name of the surface. 1-64 chars."
  2. Changed1 schema field changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders, `video` for a tab of videos people flip through."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders (put a local file in with `create_file_upload` then `upload_file`), `video` for a tab of videos people flip through (a local video goes in with `create_video_upload` then `add_video`)."
  3. Changed2 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders, `video` for a tab of videos people flip through."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "table",
-  "doc",
-  "html",
-  "files"
-]New value: +[
+  "table",
+  "doc",
+  "html",
+  "files",
+  "video"
+]
  4. Changed2 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab, `files` for uploaded files + folders."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "table",
-  "doc",
-  "html"
-]New value: +[
+  "table",
+  "doc",
+  "html",
+  "files"
+]
  5. Changed2 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for a sandboxed HTML mockup tab."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "table",
-  "doc"
-]New value: +[
+  "table",
+  "doc",
+  "html"
+]
  6. Changed3 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for sandboxed HTML/CSS/JS."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "table",
-  "doc",
-  "html"
-]New value: +[
+  "table",
+  "doc"
+]
    • changedInput schema / properties / name / description
      Previous value: -"Display name shown on the tab. 1-64 chars. Make it specific to what the surface holds (e.g. 'Findings', 'Weekly schedule', 'Architecture diagram'). Avoid generic placeholders like 'Notes' or 'Sheet' — those leave every tab in a multi-surface workspace looking the same."New value: +"Display name shown on the tab. 1-64 chars."
  7. Changed3 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"Surface kind. `table` for rows + columns, `doc` for TipTap body."New value: +"Surface kind. `table` for rows + columns, `doc` for TipTap body, `html` for sandboxed HTML/CSS/JS."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "table",
-  "doc"
-]New value: +[
+  "table",
+  "doc",
+  "html"
+]
    • changedInput schema / properties / name / description
      Previous value: -"Display name shown on the tab. 1-64 chars."New value: +"Display name shown on the tab. 1-64 chars. Make it specific to what the surface holds (e.g. 'Findings', 'Weekly schedule', 'Architecture diagram'). Avoid generic placeholders like 'Notes' or 'Sheet' — those leave every tab in a multi-surface workspace looking the same."
  8. Changed1 schema field changed
    • changedInput schema / properties / slug / description
      Previous value: -"The workspace slug. Accepts either the bare slug ('my-workspace') or the org-prefixed form ('my-org/my-workspace') as shown in the dashboard URL — both resolve to the same workspace."New value: +"The workspace slug. Accepts either the bare slug ('my-workspace') or the org-prefixed form ('my-org/my-workspace') as shown in the dashboard URL; both resolve to the same workspace."
  9. First observed

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: editor role required, emits surface.created for live listeners, slug collision auto-suffixes, table starts empty. It omits idempotency/rate limits, but the auth requirement and event emission are the key operational traits an agent needs.

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?

Dense but front-loaded: the core action leads, kinds are enumerated next, and per-kind detail follows. Every sentence routes the agent to a concrete sibling tool, though the kind-specific block is long and could be tighter.

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 five-kind creation tool with no output schema and no annotations, the description covers role requirements, event emission, and the post-creation workflow for each kind. The one gap is the ambiguous slug/surface_slug naming, which leaves the agent guessing which parameter carries the surface slug.

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 coverage is 100%, so baseline is 3, and the description does add value (columns start empty for tables, slug auto-derivation and collision suffix, columns ignored for non-table kinds). However it mislabels the surface slug as `slug` and calls it optional, while the schema defines `slug` as the required workspace slug and puts the surface slug in `surface_slug` — a naming/semantics inconsistency that undercuts an otherwise rich description.

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+resource ('Create a new surface inside a workspace') and enumerates the five kinds, making it clearly distinct from list_surfaces, update_surface, and delete_surface. An agent immediately understands what is created and the allowed variants.

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?

Gives concrete follow-up routing per kind (write html via update_html, files via upload_file/list_files, videos via add_video/create_video_upload). It stops short of stating when NOT to use it or comparing directly against update_surface/create_workspace, but the per-kind next-step guidance is unusually actionable.

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

All Dock toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources