Skip to main content
Glama
Sign In

Dock

by ai.trydock
OverviewDiscussionsAdmin

update_surface

Rename, reslug, reorder, restore, OR replace the column schema of a surface. Pass any subset of name, new_surface_slug, position, columns, archived. Restore: pass archived: false with the archived surface's surface_slug (find it with list_surfaces archived: true) to unarchive it; its rows and doc body come back, it is placed last among the workspace's surfaces, and it emits surface.unarchived. Refused if another live surface now owns that slug. To archive, use delete_surface. Position is 0-based and is normalised across siblings so positions stay contiguous. Editor role required. Emits surface.updated.

Column schema (columns): table surfaces only. Pass a full ColumnDef[] to REPLACE the existing schema atomically (no per-column add/remove churn, no row data loss — existing row.data keys that are no longer mapped are preserved on disk and surface in future writes' unmapped_fields). Each ColumnDef = { key, label, type, position, width?, hidden?, description?, options? }. Type ∈ text | longtext | number | status | person | date | url | checkbox | select; options lists the allowed values of a status/select column. Reject 400 with a table-only error if the surface is a doc or html kind. Use get_workspace_schema first to fetch the current shape, mutate it, send it back.

Input Schema

NameRequiredDescriptionDefault
nameNoNew display name. 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. Full replacement ColumnDef[] for the surface's table schema. Table surfaces only — doc/html surfaces 400 with a table-only error. Each item: `{ key, label, type, position, width?, hidden?, description?, options? }`. type ∈ text|longtext|number|status|person|date|url|checkbox|select. Existing row.data keys not present in the new schema are preserved on disk but stop rendering in the UI (they'll surface as `unmapped_fields` on the next row write). Use get_workspace_schema → mutate → send the full array back; this is a REPLACE, not a merge.
archivedNoPass `false` to restore (unarchive) an archived surface. No-op on a live surface. Only `false` is accepted; archive with `delete_surface`.
positionNo0-based position among the workspace's surfaces. Other surfaces shift to keep positions contiguous.
surface_slugYesThe current slug of the surface to update.
new_surface_slugNoNew slug for the surface (lowercase kebab-case, 3-64 chars). Must be unique within the workspace.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / archived
      Added value: +{
+  "description": "Pass `false` to restore (unarchive) an archived surface. No-op on a live surface. Only `false` is accepted; archive with `delete_surface`.",
+  "type": "boolean"
+}
  2. Changed2 schema fields changed
    • changedInput schema / properties / columns / description
      Previous value: -"Optional. Full replacement ColumnDef[] for the surface's table schema. Table surfaces only — doc/html surfaces 400 with a table-only error. Each item: `{ key, label, type, position, width?, hidden?, description?, options? }`. type ∈ text|longtext|url|status|owner|date|number. Existing row.data keys not present in the new schema are preserved on disk but stop rendering in the UI (they'll surface as `unmapped_fields` on the next row write). Use get_workspace_schema → mutate → send the full array back; this is a REPLACE, not a merge."New value: +"Optional. Full replacement ColumnDef[] for the surface's table schema. Table surfaces only — doc/html surfaces 400 with a table-only error. Each item: `{ key, label, type, position, width?, hidden?, description?, options? }`. type ∈ text|longtext|number|status|person|date|url|checkbox|select. Existing row.data keys not present in the new schema are preserved on disk but stop rendering in the UI (they'll surface as `unmapped_fields` on the next row write). Use get_workspace_schema → mutate → send the full array back; this is a REPLACE, not a merge."
    • changedInput schema / properties / position / description
      Previous value: -"0-based index in the tab strip. Other surfaces shift to keep positions contiguous."New value: +"0-based position among the workspace's surfaces. Other surfaces shift to keep positions contiguous."
  3. Changed1 schema field changed
    • addedInput schema / properties / columns
      Added value: +{
+  "description": "Optional. Full replacement ColumnDef[] for the surface's table schema. Table surfaces only — doc/html surfaces 400 with a table-only error. Each item: `{ key, label, type, position, width?, hidden?, description?, options? }`. type ∈ text|longtext|url|status|owner|date|number. Existing row.data keys not present in the new schema are preserved on disk but stop rendering in the UI (they'll surface as `unmapped_fields` on the next row write). Use get_workspace_schema → mutate → send the full array back; this is a REPLACE, not a merge.",
+  "items": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "type": "array"
+}
  4. 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."
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and delivers: restore returns rows and doc body, places the surface last, emits `surface.unarchived`, and is refused if another live surface owns the slug; column replacement is atomic with no row data loss and unmapped keys preserved; editor role required; emits `surface.updated`; 400 table-only error on doc/html surfaces. This is unusually rich disclosure of side effects, permissions, and failure modes.

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 operation list and uses bold section headers to separate the restore and column-schema concerns, so it scans well despite length. It loses a point because the column/archived material largely restates the schema descriptions rather than adding new information.

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?

No output schema and no annotations, yet the description covers the emitted events, the permission requirement, the restore lifecycle including refusal conditions, error behavior, and the intended multi-step workflow. An agent has everything needed to invoke it correctly and interpret the outcome.

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%, so baseline is 3, but the description adds meaning: `position` normalisation keeps siblings contiguous, `columns` is a REPLACE not a merge with 0-based semantics and preserved unmapped fields, and `archived: false` is the only accepted value for restore. It overlaps heavily with the schema text, which caps it below 5.

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 cluster and resource ('Rename, reslug, reorder, restore, OR replace the column schema of a surface') and explicitly names the sibling it does not replace ('To archive, use delete_surface'). An agent can distinguish it from add_column, delete_surface, and update_row without opening a schema.

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?

Gives explicit when-to-use rules: restore via `archived: false` plus `list_surfaces archived: true` to find the slug, archive via delete_surface instead, and a prescribed workflow ('Use get_workspace_schema first to fetch the current shape, mutate it, send it back'). Alternatives and exclusions are named, not implied.

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