Skip to main content
Glama
xunji-private-mcp

xunji-private-mcp

by Vdk1639

mutate_agent_templates

DestructiveIdempotent

Applies confirmed template creates, updates, deletes, and folder renames for a single Agent folder, using mutation IDs for safe retries and version checks.

Instructions

Apply confirmed changes to the single Agent folder.

First sync the templates. To create, pass stable client_id, name, and public movements with official Chinese names. To update, pass template_id, its base_version, and changed name/color/movements or native movement/rules. Specified movement lists replace the entire list. A delete uses template_id and base_version. To rename the folder, pass folder_update with name and the folder's current base_version. Reuse mutation_id for the same change. A new template is allowed to recreate a missing Agent folder.

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": {
      "mutation_id": "<mutation_id>"
    },
    "name": "mutate_agent_templates"
  }
}

Input Schema

NameRequiredDescriptionDefault
deletesNo
upsertsNo
mutation_idYes
folder_updateNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare destructiveHint, idempotentHint, and openWorldHint, but the description adds material context: specified movement lists replace the entire list (a destructive replacement semantic), a new template may recreate a missing Agent folder (a side effect), and mutations must follow a sync. The mutation_id reuse sentence largely restates idempotentHint, so not everything is net-new.

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-loads purpose in one sentence, then walks operations in a compact sequence (sync, create, update, delete, rename, idempotency, folder recreation). Dense but nearly every sentence carries operational information; the only slightly redundant item is the mutation_id reuse line.

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 destructive, idempotent mutation tool with no output schema and no schema-level parameter documentation, this covers prerequisites, per-mode argument requirements, replacement semantics, and folder-recreation side effects. It does not describe failure behavior or the response shape, and the internal object fields for upserts/deletes stay implied.

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% and all four top-level parameters are free-form objects or strings, so the description must carry the meaning. It does so for template_id, base_version, client_id, name, color, movements, native rules, folder_update, and mutation_id. It stops short of enumerating the exact key shapes inside the 'upserts' and 'deletes' array items, which remains implicit.

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?

States a specific verb (apply confirmed changes) and resource (the single Agent folder), then enumerates the concrete operation modes it covers: create, update, delete, and folder rename. An agent can tell it apart from sync_agent_templates because the description positions syncing as a prerequisite step rather than something this tool does.

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 preconditions and per-operation routing: sync first, then create with stable client_id/name/public movements, update with template_id plus base_version, delete with template_id plus base_version, and rename via folder_update with the folder's current base_version. It also tells the caller to reuse mutation_id for the same change, which defines a clear retry pattern.

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