Skip to main content
Glama
Podcast MCP
by calebn

submit_document_command_tool

Submits a document command by type when no named edit tool covers it, validates the payload against the type schema, and applies an undoable edit to the open Studio project.

Instructions

Submit any document command by type: the edit a named tool does not cover.

Studio's own edits are document commands, and this reaches every type by name. The payload is checked against the type's schema (document_command_schema_tool) and an unknown top-level field is refused. The edit is a typed journal row and one history step, reaches an open Studio tab and is undoable with history_undo. Prefer the named tool when one exists: it adds the safety checks and options that tool documents. A type whose named tool does work a bare submit cannot (InsertSegment) is refused with the tool to use. Reuse command_id only to retry the same edit. Errors: document_command_unknown, document_command_not_generic, invalid_payload.

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": {
      "command_type": "<command_type>",
      "payload": "<payload>"
    },
    "name": "submit_document_command_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
payloadYes
command_idNo
command_typeYes
project_pathNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.4

TDQS

A4.3/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 so well: payload is validated against the type's schema, unknown top-level fields are rejected, the edit becomes a typed journal row plus one history step, it reaches an open Studio tab, and it is undoable via 'history_undo'. It also lists the three error codes. The remaining gap is preconditions such as whether an open project/tab session is strictly required or any permission constraints.

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 fallback role is front-loaded in the first clause, followed by validation, effects, and error codes in a logical order with no filler sentences. Density is high and a couple of clauses (e.g. 'Studio's own edits are document commands') add framing more than actionable information, but nothing is wasteful enough to obscure the key guidance.

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 generic escape-hatch mutation tool this covers purpose, routing, validation behavior, undo semantics, and named error codes, and an output schema exists so return values needn't be described. The only shortfall is that 'project_path' semantics and any session prerequisites are left to the schema, which documents neither.

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 description coverage is 0%, so the description must compensate and it does partially: 'command_type' is the type name checked against that type's schema, 'payload' is validated with unknown top-level fields refused, and 'command_id' is for retrying the same edit. 'project_path' is never mentioned and no payload-format guidance or example is given, leaving roughly a quarter of the parameters unexplained.

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 states a specific verb and resource ('submit any document command by type') and immediately frames the scope as the fallback for edits no named tool covers. It names the sibling it complements ('document_command_schema_tool') and the sibling it defers to ('the named tool'), so an agent can separate it from both without inspecting either 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?

It gives explicit routing: 'Prefer the named tool when one exists' because named tools add safety checks and options, and it says a type handled by a richer named tool ('InsertSegment') is refused with the tool to use. It also scopes 'command_id' reuse to retries only, which prevents an obvious misuse pattern.

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

Deploy Server

Other Tools