Skip to main content
Glama

maket_structured_workspace

Create and manage schema-driven Structured Workspaces with typed collections, item CRUD, templates, validation, and cursor-based views.

Instructions

HTTP read increment: create/update_definition accept data_source={kind:'http',baseUrl,collectionId,bindingId,auth?:'env:NAME',list:{path,params:{cursor,limit,sort,text?,filters?},itemsPointer,nextPointer,totalPointer?,revisionPointer?},get:{path:'items/{id}',dataPointer?,revisionPointer?}}. One collection/binding, declared identity and sortBy required; grouping unavailable. Query parameters carry text/cursor/limit verbatim, sort/filters as JSON. Item data is each list object; detail is the whole response or dataPointer. nextPointer gives a server token or null; no total unless declared. Bearer auth is resolved only in the server environment. Source records are fetched by requested batch; opening a detail rereads GET. HTTP is read-only in this increment (writes refuse read_only); revisions stay opaque. view retries an unavailable source, reopen refreshes a detail. No background poll or webhook. When to use: create and operate a Structured Workspace — a schema-driven collection of items, listed in an index and opened as Maket documents built from templates.

Method (full recipe: maket_learn action=topic topic=structured-workspaces): 1) create with a data_schema alone that has a required "id" property (string), one value per item: Maket identifies the items by "/id" — or declare another identity per collection, e.g. representation_schema={"collections":{"items":{"name":"Items","identity":"/code"}}} — and Maket writes the index, detail, card templates and the detail form itself, in the Workspace category; 2) add_item; 3) check, which must answer verdict ready. Inline template HTML (detailTemplateHtml, compactTemplateHtml, indexTemplateHtml, detailForm) or names of existing template documents are the optional second and third paths. Identity: every collection has an identity, a JSON Pointer to a required string or number property of its items (e.g. "/code"); without one, "/id" when the schema requires an id property. Its value, as a string, is the item id used everywhere (item=, documents, cursors) and is unique across the whole Workspace, all collections included; Maket never generates one. add_item refuses data without it, or a value another item of the Workspace already bears (invalid_record, naming that item); update_item refuses a change of it: delete and add the item again instead. The identity of a collection holding items cannot be changed. create and update_definition refuse a definition with errors (isError, one line per error with collection, path and fix) and keep the previous definition; allow_incomplete=true persists it anyway. add_item and update_item refuse data that breaks the schema with its path, rule and fix.

The data schema validates every item. The representation schema declares one or more collections; each collection owns its global template and binds concrete schema paths to compact and detail templates. The item source holds the item data; an item's document is created from its detail template when the item is opened or exported. Template-controlled pages are synchronized from the template; instance-owned pages remain in the same document. Reading items is a cursor query: view answers one batch of item summaries for one collection (collection, default the first) with next (an opaque cursor, absent once the listing is exhausted), total and the group counts. Pass text (searches searchFields, by default every text property, ignoring case and accents), filters ([{"field":"/status","op":"eq","value":"todo"}], op in for a list), sort ({"field":"/title","direction":"descending"}) and batch (default indexPageSize, 50; at most 500) to start a new query, which also becomes the window every client sees in the index. To read the next batch, pass cursor= with the same query arguments (the answer gives the call in more): it reads the source directly and never depends on the shared window: no item that existed before and kept its sort value is skipped or read twice, while an item whose sort value changes during paging may move across the cursor. There is no page number and no previous: a new query restarts from the first item. view with neither query nor cursor answers the first batch of the collection's own order. Optional collection grouping: groupBy is a JSON Pointer into item data (e.g. "/status"), groupOrder lists group values to place first, and pageSize (default 24) caps the compact cards per collection page. With groupBy, each item slot receives a group header followed by its cards and the collection document flows onto as many pages as needed; without it, the collection stays one page. Optional collection sort: sortBy is a JSON Pointer into item data (e.g. "/place") and sortDirection is "ascending" (default) or "descending"; cards are ordered by that value inside each group, or across the slot without groupBy, items without a value last and ties in item id order; without sortBy, insertion order stays. list — list Structured Workspaces, each prefixed with ready or incomplete. view — verdict and finding count first, then the definition, item counts, pinned items, owned documents, one batch of the collection window (see the cursor query above), and reading: the reading path of that collection's index in Maket. check — the doctor: verdict ready or not ready and every finding with severity, object, sentence, fix and next call. Never writes. create — create a workspace from a data schema, with an optional representation schema; refuses errors unless allow_incomplete=true. update_definition — validate and replace the data and/or representation contract, then update the item and index documents that exist; an erroneous definition is refused and the previous one kept unless allow_incomplete=true. add_item — validate data and write the item to its source under the id its identity property holds; its document is created when the item is opened. update_item — replace item data with optimistic revision control. delete_item — delete the item from its source, with its document when it was opened. sync_template — propagate current detail-template pages while preserving instance-owned pages. rename — rename the Workspace without regenerating owned documents. delete — atomically delete the Workspace and every document, state revision, and annotation it owns.

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": {
      "action": "<action>"
    },
    "name": "maket_structured_workspace"
  }
}

Input Schema

NameRequiredDescriptionDefault
dataNo
itemNo
sortNo
textNo
batchNo
actionYes
cursorNo
bindingNo
filtersNo
new_nameNo
workspaceNo
collectionNo
data_schemaNo
data_sourceNo
descriptionNo
document_nameNo
allow_incompleteNo
expected_revisionNo
representation_schemaNo
expected_workspace_revisionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.3.1
    • addedInput schema / properties / data_source
      Added value: +{
      +  "oneOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "kind": {
      +          "const": "local",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "kind"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "auth": {
      +          "pattern": "^env:[A-Za-z_][A-Za-z0-9_]*$",
      +          "type": "string"
      +        },
      +        "baseUrl": {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        "bindingId": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "collectionId": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "get": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "dataPointer": {
      +              "type": "string"
      +            },
      +            "path": {
      +              "type": "string"
      +            },
      +            "revisionPointer": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "path"
      +          ],
      +          "type": "object"
      +        },
      +        "kind": {
      +          "const": "http",
      +          "type": "string"
      +        },
      +        "list": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "itemsPointer": {
      +              "type": "string"
      +            },
      +            "nextPointer": {
      +              "type": "string"
      +            },
      +            "params": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "cursor": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "filters": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "limit": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "sort": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "text": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "cursor",
      +                "limit",
      +                "sort"
      +              ],
      +              "type": "object"
      +            },
      +            "path": {
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "revisionPointer": {
      +              "type": "string"
      +            },
      +            "totalPointer": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "path",
      +            "params",
      +            "itemsPointer",
      +            "nextPointer"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "kind",
      +        "baseUrl",
      +        "collectionId",
      +        "bindingId",
      +        "list",
      +        "get"
      +      ],
      +      "type": "object"
      +    }
      +  ]
      +}
    • changedInput schema / properties / filters / items / properties / value / anyOf
      Previous value: -[
      -  {
      -    "anyOf": [
      -      {
      -        "type": "string"
      -      },
      -      {
      -        "type": "number"
      -      },
      -      {
      -        "type": "boolean"
      -      },
      -      {
      -        "type": "null"
      -      }
      -    ]
      -  },
      -  {
      -    "items": {
      -      "anyOf": [
      -        {
      -          "type": "string"
      -        },
      -        {
      -          "type": "number"
      -        },
      -        {
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ]
      -    },
      -    "type": "array"
      -  }
      -]New value: +[
      +  {
      +    "type": [
      +      "string",
      +      "number",
      +      "boolean",
      +      "null"
      +    ]
      +  },
      +  {
      +    "items": {
      +      "type": [
      +        "string",
      +        "number",
      +        "boolean",
      +        "null"
      +      ]
      +    },
      +    "type": "array"
      +  }
      +]
    • removedInput schema / properties / representation_schema / properties / collections / additionalProperties / properties / groupOrder / items / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / representation_schema / properties / collections / additionalProperties / properties / groupOrder / items / type
      Added value: +[
      +  "string",
      +  "number",
      +  "boolean",
      +  "null"
      +]
  2. Addedv2.2.0

TDQS

A4.1/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 discloses rich behavioral traits: HTTP source operations are read-only in this increment, writes refuse read_only, revisions stay opaque, definitions with errors are rejected, identity uniqueness is enforced, cursors are opaque and may move across pages if sort values change, and no background polling or webhooks exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely long and opens with a dense HTTP data_source paragraph before stating the general 'When to use' purpose. Much of the detail is useful for a complex tool, but the structure is not front-loaded and some sections could be tightened.

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 20-parameter tool with no output schema and no annotations, the description is largely complete: it covers action behavior, schema and representation semantics, identity rules, cursor paging, grouping, sorting, and error handling. Minor gaps remain around a few parameter meanings.

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 0%, so the description must compensate. It thoroughly explains data_source, representation_schema, cursor, sort, filters, batch, allow_incomplete, and identity semantics, but leaves a few parameters such as description, document_name, binding, and expected_workspace_revision without explicit meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this tool creates and operates a Structured Workspace — a schema-driven collection of items with index and Maket document pages. It distinguishes the resource well but does not explicitly contrast its role with siblings like maket_workspace or maket_collection.

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?

It provides an explicit 'When to use' section and a three-step creation recipe, plus action-level descriptions. It points to maket_learn for a fuller recipe but does not state when to choose this tool over sibling alternatives or when not to use it.

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