Skip to main content
Glama

Dock

by ai.trydock
OverviewDiscussionsAdmin

create_workspace

Create a new workspace in the caller's org. Works for both user and agent callers; agent-created workspaces attribute to the agent and enroll the agent's owning user as a co-owner so the human sees it in their dashboard. The new workspace is seeded with one primary surface matching mode: doc → a Notes tab (for prose), table → a Sheet tab (for records), html → a Mockup tab (sandboxed HTML preview). Decide the surface before you create: prose (briefs, notes, summaries, drafts) → doc; records with shared columns (tasks, leads, rows) → table; a deliverable that IS html (a page, mockup, dashboard, or visual meant to be seen or shared) → html, then write it with update_html — never to a local file, which the human can't see. If you omit mode, pass initial_markdown to signal a doc; with neither mode nor initial_markdown, an agent caller gets a guided error asking it to choose doc or table (so you never silently land on the wrong surface). An explicit mode is always honored. html is opt-in — never inferred for ambiguous content — so pass it explicitly when the deliverable is html (a mockup, page, or dashboard the user asked for), and only then. Add more tabs of any kind later via create_surface. Agent-created workspaces default to org-visibility so sibling agents in the same org aren't 403'd. For prose content (briefs, summaries, changelogs) pass initial_markdown to seed the doc body in one call; the markdown is converted server-side, no need to hand-build ProseMirror JSON.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNoKind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview): opt in by passing it explicitly whenever the deliverable IS html — a landing-page mockup, a dashboard, a design preview, any page meant to be looked at — and write it with `update_html`; it is never inferred for ambiguous content. Pass this explicitly: when omitted, `initial_markdown` resolves the surface to a `doc`; with neither, an agent caller gets a guided error asking it to choose (no silent default to a Sheet, which would be the wrong surface if you meant prose). Add more tabs of any kind via `create_surface` later.
nameYesThe workspace name. Required. Used to derive a slug if you don't pass one.
slugNoOptional URL-friendly slug (lowercase, kebab-case, 3-64 chars). Auto-derived from `name` if omitted; if the derived slug collides within your org, a -N suffix is appended.
initial_markdownNoOptional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Ignored when mode='html' (no markdown equivalent for HTML surfaces — use `update_html` after create). Use this for any prose-shaped output (briefs, summaries, status updates, changelog entries) instead of create + update_doc with hand-built JSON.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / mode / description
      Previous value: -"Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews), opt-in only. Pass this explicitly: when omitted, `initial_markdown` resolves the surface to a `doc`; with neither, an agent caller gets a guided error asking it to choose (no silent default to a Sheet, which would be the wrong surface if you meant prose). Add more tabs of any kind via `create_surface` later."New value: +"Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview): opt in by passing it explicitly whenever the deliverable IS html — a landing-page mockup, a dashboard, a design preview, any page meant to be looked at — and write it with `update_html`; it is never inferred for ambiguous content. Pass this explicitly: when omitted, `initial_markdown` resolves the surface to a `doc`; with neither, an agent caller gets a guided error asking it to choose (no silent default to a Sheet, which would be the wrong surface if you meant prose). Add more tabs of any kind via `create_surface` later."
  2. Changed1 schema field changed
    • changedInput schema / properties / mode / description
      Previous value: -"Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews), opt-in only. Pass this explicitly rather than relying on the fallback: when omitted it defaults to 'doc' if initial_markdown is supplied, otherwise 'table' — so a bare create with no content silently becomes a Sheet, which is the wrong surface if you meant to write prose. Add more tabs of any kind via `create_surface` later."New value: +"Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews), opt-in only. Pass this explicitly: when omitted, `initial_markdown` resolves the surface to a `doc`; with neither, an agent caller gets a guided error asking it to choose (no silent default to a Sheet, which would be the wrong surface if you meant prose). Add more tabs of any kind via `create_surface` later."
  3. Changed1 schema field changed
    • changedInput schema / properties / mode / description
      Previous value: -"Kind of the seeded primary surface. `table` mints a Sheet tab, `doc` mints a Notes tab, `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews). Auto-defaults to 'doc' when initial_markdown is provided, 'table' otherwise; `html` is opt-in. Add more tabs of any kind via `create_surface` later."New value: +"Kind of the seeded primary surface — choose by what you're about to write. `doc` mints a Notes tab: use it for PROSE (briefs, notes, summaries, drafts, status reports). `table` mints a Sheet tab: use it for RECORDS (tasks, leads, rows, anything with shared columns). `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews), opt-in only. Pass this explicitly rather than relying on the fallback: when omitted it defaults to 'doc' if initial_markdown is supplied, otherwise 'table' — so a bare create with no content silently becomes a Sheet, which is the wrong surface if you meant to write prose. Add more tabs of any kind via `create_surface` later."
  4. Changed3 schema fields changed
    • changedInput schema / properties / initial_markdown / description
      Previous value: -"Optional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Use this for any prose-shaped output (briefs, summaries, status updates, changelog entries) instead of create + update_doc with hand-built JSON."New value: +"Optional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Ignored when mode='html' (no markdown equivalent for HTML surfaces — use `update_html` after create). Use this for any prose-shaped output (briefs, summaries, status updates, changelog entries) instead of create + update_doc with hand-built JSON."
    • changedInput schema / properties / mode / description
      Previous value: -"Default-view preference for the first tab. Auto-defaults to 'doc' when initial_markdown is provided, 'table' otherwise. Picks the kind of the seeded primary surface; you can add more tabs of either kind via `create_surface` later. A workspace can hold any combination of doc and table surfaces, one or many of either."New value: +"Kind of the seeded primary surface. `table` mints a Sheet tab, `doc` mints a Notes tab, `html` mints a Mockup tab (sandboxed HTML preview, for landing-page mockups + design previews). Auto-defaults to 'doc' when initial_markdown is provided, 'table' otherwise; `html` is opt-in. Add more tabs of any kind via `create_surface` later."
    • changedInput schema / properties / mode / enum
      Previous value: -[
-  "table",
-  "doc"
-]New value: +[
+  "table",
+  "doc",
+  "html"
+]
  5. Changed2 schema fields changed
    • changedInput schema / properties / initial_markdown / description
      Previous value: -"Optional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Use this for any prose-shaped output — briefs, summaries, status updates, changelog entries — instead of create + update_doc with hand-built JSON."New value: +"Optional Markdown body to seed the workspace's doc surface on create. CommonMark + GFM (tables, task lists, strikethrough). When provided AND mode is omitted, mode defaults to 'doc'. Skips the empty default-column scaffolding too. Use this for any prose-shaped output (briefs, summaries, status updates, changelog entries) instead of create + update_doc with hand-built JSON."
    • changedInput schema / properties / mode / description
      Previous value: -"Default-view preference for the first tab. Auto-defaults to 'doc' when initial_markdown is provided, 'table' otherwise. Picks the kind of the seeded primary surface; you can add more tabs of either kind via `create_surface` later — a workspace can hold any combination of doc and table surfaces, one or many of either."New value: +"Default-view preference for the first tab. Auto-defaults to 'doc' when initial_markdown is provided, 'table' otherwise. Picks the kind of the seeded primary surface; you can add more tabs of either kind via `create_surface` later. A workspace can hold any combination of doc and table surfaces, one or many of either."
  6. First observed

TDQS

A4.8/5.0
Behavior5/5

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

With zero annotations, the description carries the full behavioral burden — and it delivers. It discloses side effects an agent would otherwise not know: agent-created workspaces attribute to the agent and enroll the owning user as co-owner; agent workspaces default to org-visibility to avoid 403s on sibling agents; seeding produces one primary surface; `initial_markdown` is converted server-side. This goes well beyond what the schema or any annotation could convey.

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?

At ~230 words this is long, but the tool is genuinely complex — interdependent params, agent-vs-user behavior differences, error paths, and sibling routing — so most sentences earn their place. It's front-loaded with the core purpose before the conditional logic. The main inefficiency is redundancy: the mode→surface mapping and the `initial_markdown` prose guidance are restated in the schema's param descriptions, and a few clauses (e.g., the html opt-in caveat) appear twice within the description itself.

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?

For a 4-param creation tool with one required enum and no annotations, this is remarkably complete: it covers caller type differences, co-ownership side effects, visibility defaults, seeded-surface mapping, error behavior on ambiguity, markdown handling, and explicit routing to `create_surface` and `update_html`. The only minor absences (explicit return format, permission prerequisites) are not critical for a create tool whose invocation conditions are exhaustively specified.

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 description coverage is 100% and the schema's own param descriptions are unusually rich (especially `mode`'s mapping guidance). The description nonetheless adds genuine value beyond the schema: the parameter-interplay rule (omit `mode` + pass `initial_markdown` → signals `doc`), the warning against silently landing on the wrong surface, and the practical note that markdown is converted server-side so the agent need not hand-build ProseMirror JSON.

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 + scope: "Create a new workspace in the caller's org." The seeding behavior (doc→Notes, table→Sheet, html→Mockup) precisely defines what the created resource contains, and the description explicitly distinguishes itself from siblings by pointing to `create_surface` for adding tabs later. An agent cannot confuse this with `update_workspace` or `create_surface`.

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?

Provides explicit conditional routing: prose → `doc`, records → `table`, html deliverable → `html` then `update_html` ("never to a local file"). States when NOT to infer html ("opt-in — never inferred for ambiguous content"), what happens with omitted `mode`/`initial_markdown` (guided error, no silent wrong-surface default), and names the sibling (`create_surface`) for later tab creation. This is textbook when/when-not/alternatives guidance.

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