This MCP server provides 16 tools to control Autodesk Maya via natural language through Claude, covering 3D modeling, animation, materials, lighting, rendering, scene management, AI-powered 3D generation, and documentation search.
Core Maya Operations:
Primitives: Create cubes, spheres, cylinders, cones, planes, and tori with position, scale, and rotation (maya_create_primitive)
Materials: Create and assign lambert, blinn, phong, or Arnold standard surface materials with RGB color (maya_assign_material)
Transforms: Move, rotate, or scale objects in world or local space with relative or absolute modes (maya_transform)
Lighting: Create directional, point, spot, area, or ambient lights with intensity and color (maya_create_light)
Cameras: Create cameras with focal length and look-at targeting (maya_create_camera)
Mesh Operations: Extrude, bevel, boolean (union/difference/intersection), combine, separate, and smooth meshes (maya_mesh_operation)
Animation: Set keyframes on any attribute with tangent control (auto/linear/flat/spline/step) (maya_set_keyframe)
File Import: Import OBJ, FBX, GLB/GLTF, Alembic, Maya (MA/MB), and BVH mocap files with namespace and scale options (maya_import_file)
Viewport Capture: Capture the viewport as PNG/JPG for visual verification (maya_viewport_capture)
Session Management (maya_session):
Ping connection, launch Maya, create/save scenes, list objects, take scene snapshots
Delete objects (with wildcard support and safety checks)
Execute arbitrary Python in Maya with safety scanning, timeout, and progress heartbeats
Create shelf buttons, read the audit log, drive the Toolkit publisher (tk-multi-publish2), generate turntable playblasts (.mov), and render single-frame Arnold stills
AI-Powered 3D Generation (optional addons):
Vision3D (maya_vision3d): Image-to-3D and text-to-3D generation, AI texturing of existing meshes, async job polling and result downloading
World Labs (maya_worldlabs): Generate Gaussian-splat environments from images, convert to Arnold-readable PLY, and load into Maya as aiGaussianSplat objects with cameras and HDR panoramas
Intelligence & RAG:
Documentation Search (search_maya_docs): Hybrid semantic + BM25 search with HyDE query expansion across maya.cmds, PyMEL, Arnold/mtoa, Maya-USD, and anti-patterns corpora
Safety Module: Scans all code for 14+ dangerous patterns before execution, blocking and explaining issues with safe alternatives
Self-Learning (learn_pattern): Save validated working patterns to the RAG knowledge base for future sessions (with model trust gates)
Session Stats (session_stats / reset_session_stats): Report token efficiency, RAG savings, safety blocks, and patterns learned
Provides tools for creating, manipulating, and managing 3D scenes in Autodesk Maya, including primitive creation, material assignment, transformations, lighting, cameras, mesh operations, keyframing, file import, viewport capture, session management, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@maya-mcp create a red sphere and a blue cube"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Control Autodesk Maya with natural language using Claude and the Model Context Protocol (MCP)
Experimental project — use at your own risk. This is an independent, unofficial experiment created with Claude Code. It is not affiliated with, endorsed by, or officially supported by Autodesk in any way. The Maya name and trademarks belong to Autodesk, Inc.
Executing AI-generated code inside a live Maya session carries real risks: unexpected crashes, loss of unsaved work, unintended modifications to scenes, rigs, or assets. Always work on a duplicate or test scene. Never run this on production material without a full backup. The author(s) accept no responsibility for data loss, corruption, or any other damage resulting from its use.
Interactive, auto-published map of this codebase — modules, functions, call/import edges and community clusters — rebuilt by graphify and deployed to GitHub Pages on every push to src/:
abrahamadsk.github.io/maya-mcp · part of the MCP ecosystem graph hub.
MCP server for Autodesk Maya — 16 MCP tools with RAG-powered documentation search, anti-hallucination safety, self-learning patterns, and optional AI-driven 3D generation via the Vision3D addon.
Related MCP server: Maya MCP Server
Beyond primitives, maya-mcp handles real production tasks: polygon modeling (extrude, bevel, boolean, combine, smooth), animation keyframing with tangent control, multi-format I/O (OBJ, FBX, GLTF, Alembic, USD, MA/MB), viewport capture/playblast, full scene snapshots, and shelf button creation. All operations use undo chunks for safe rollback.
Optionally integrates with Vision3D for image-to-3D and text-to-3D generation. Non-blocking async workflow: submit job → poll status → download results → import into Maya. Runs on a remote GPU server so your local machine stays responsive. Vision3D is not required — maya-mcp works fully without it.
A dockable Qt panel that lives inside Maya as a workspaceControl tab (next to the Attribute Editor). Provides a chat interface to Claude with live Maya context (scene name, object count, selection, renderer). Installs automatically — the first time Claude connects to Maya (via maya_ping or maya_launch), the MCP Pipeline menu and panel are injected into the running Maya session. No manual userSetup.py editing required. The panel persists across Maya sessions — if left open, it auto-restores on next launch. Uses PySide2 (Maya 2023–2024) or PySide6 (Maya 2025+) automatically via a compatibility shim. All MCP servers (maya-mcp, fpt-mcp, flame-mcp) are accessible from the panel through Claude Code CLI.
Works alongside fpt-mcp (ShotGrid/Flow Production Tracking) and flame-mcp (Autodesk Flame). Each DCC has its own embedded console, and all consoles access all MCP servers via Claude Code CLI. When multiple servers are configured, Claude can orchestrate end-to-end VFX workflows across applications. Consistent architecture across all three servers.
Review previews are colour-correct and deterministic. The Viewport 2.0 capture paths (review_turntable, maya_viewport_capture) pin the colour-management view transform before the playblast and restore it after, so a version preview matches the viewport instead of riding the session's current view. The view is configurable (config.json → review_view_transform, default Un-tone-mapped (sRGB) — the view of Maya's built-in default OCIO config). For Arnold file renders, color_policy.py (and docs/ARNOLD_API.md) provide a preview-vs-EXR policy: bake the output transform for an 8-bit preview, but force the driver to Raw for scene-linear EXRs — the guardrail that keeps a display transform out of the EXRs the comp/Flame stage consumes.
Claude / LLM
↕ MCP protocol (stdio)
FastMCP server (src/maya_mcp/server.py) — 16 MCP tools
├── RAG engine (src/maya_mcp/rag/)
│ ├── ChromaDB + BM25 hybrid search
│ ├── HyDE adaptive query expansion
│ └── In-session cache + RRF fusion
├── Safety module (src/maya_mcp/safety.py)
│ └── 14+ dangerous pattern detectors
├── Maya bridge (src/maya_mcp/maya_bridge.py)
│ └── TCP socket → Command Port :8100
└── Vision3D client (HTTP)
└── GPU server for 3D generationTool | Description |
| Create cube / sphere / cylinder / cone / plane / torus |
| Create and assign material (lambert / blinn / phong / aiStandardSurface) |
| Move / rotate / scale with world/object space and relative mode |
| Create directional / point / spot / area / ambient lights |
| Create cameras with focal length and look-at target |
| Extrude, bevel, boolean (union/diff/intersect), combine, separate, smooth |
| Keyframe any attribute with tangent control (auto/linear/flat/spline/step) |
| Import OBJ, FBX, GLB/GLTF, Alembic, MA/MB, BVH mocap with namespace and scale (streams progress; 120s budget for heavy assets, 240s for BVH) |
| Playblast screenshot to PNG/JPG at any resolution |
Tool | Description |
| Session lifecycle + generic Maya ops (see action table below) |
| Optional Vision3D addon (see action table below) |
| Optional World Labs (Marble) addon — image→Gaussian-splat environment, convert + load into Maya for Arnold (see action table below) |
Tool | Description |
| Hybrid RAG search across 5 Maya API corpora with relevance scores |
| Save validated working patterns for future sessions (with trust gates) |
| Token efficiency report: RAG savings, safety blocks, patterns learned, p_fallo |
| Zero the session counters immediately (manual companion to the 30-min idle auto-reset) |
maya_session — 12 actions)Action | Description |
| Verify connection, returns Maya version and scene info |
| Open Maya and wait for Command Port to respond (streams progress while waiting) |
| New empty scene (refuses if the scene has unsaved changes; pass confirm=true to discard them) |
| Save current scene |
| List scene objects with type and name filters |
| Full scene state: file, renderer, object counts, plugins, units |
| Delete objects with safety checks on wildcards |
| Execute arbitrary Python in Maya (safety scanning; optional timeout param up to 600s with 10s progress heartbeats) |
| Create reusable shelf buttons with custom Python commands |
| Read recent durable-audit records (read-only; requires MAYA_AUDIT_LOG=1). Optional filters: limit, tool, action, status |
| Drive the native Toolkit publisher (tk-multi-publish2) inside an engine'd Maya launched via tank. mode preview/publish, include/exclude intent tokens, comment, timeout. Captures dependencies automatically. |
| Deterministic Viewport 2.0 turntable playblast to a .mov (long op, runs in Maya). Frames the model, orbits 360° over start–end at the given fps, 16:9 / square pixels / overscan, offscreen (never Arnold), colour-managed (the review view transform is pinned and restored so the preview matches the viewport). Needs out_path (resolve via fpt tk_resolve_path, template movie_asset_publish); returns the mov plus a Version code Asset_Task to name the review Version after its task. |
| Single-frame Arnold ray-traced still to a PNG at the exact out_path (long op). This is what "a still" means — a real render, not the Viewport 2.0 grab that maya_viewport_capture does. Maya only exports a |
maya_vision3d — 7 actions, optional, requires Vision3D)Action | Description |
| Set the Vision3D server URL for the rest of this MCP session (runtime-only, asked from the user in the chat) |
| Check availability and model status of the selected server |
| Image-to-3D generation (full pipeline) |
| Text-to-3D generation |
| Texture an existing mesh with AI |
| Poll async job status |
| Download completed results to local disk |
LLMs hallucinate Maya API details constantly — wrong flag names (width= instead of w=), nonexistent commands (cmds.usdExport instead of cmds.mayaUSDExport), incorrect return types. maya-mcp includes a hybrid RAG engine (ChromaDB semantic + BM25 lexical, fused via Reciprocal Rank Fusion) with 5 curated documentation corpora covering maya.cmds, PyMEL, Arnold/mtoa, Maya-USD, and a comprehensive anti-patterns database. The LLM calls search_maya_docs before writing any unfamiliar code, getting verified syntax with relevance scores.
Short queries like "set keyframe tangent" don't match code-heavy documentation well. maya-mcp uses Hypothetical Document Embedding (HyDE) — it detects which Maya API domain the query targets (cmds, PyMEL, Arnold, USD, MEL) and wraps the query in a domain-specific code template before embedding. This bridges the gap between natural-language questions and code documentation.
Before any code reaches Maya, the safety module scans for 14+ dangerous patterns: bulk deletes without filters, undo system tampering, filesystem operations on scene files, plugin deregistration with active nodes, namespace deletions, referenced geometry modification, and more. Each pattern includes an explanation of WHY it is dangerous and a SAFE alternative.
When the RAG returns low-relevance results (< 60%) but the operation succeeds, the LLM can call learn_pattern to save the working pattern for future sessions. Model trust gates ensure only Opus/Fable can write directly to docs — other models stage candidates for human review. Knowledge grows over time without manual curation.
Every tool call tracks tokens in/out. The session_stats tool reports how much context was saved by RAG vs loading full documentation, making the efficiency gains measurable and visible.
maya-mcp/
├── src/
│ └── maya_mcp/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # FastMCP server — 16 MCP tools
│ ├── maya_bridge.py # TCP bridge → Maya Command Port :8100
│ ├── safety.py # Dangerous pattern detection (14+ patterns)
│ ├── config.example.json
│ ├── rag/
│ │ ├── config.py # Embedding model, search params, token tracking
│ │ ├── build_index.py # Chunk docs → ChromaDB + BM25 corpus
│ │ ├── search.py # Hybrid search: BM25 + semantic + HyDE + RRF
│ │ ├── index/ # ChromaDB persistent index (auto-generated)
│ │ └── corpus.json # BM25 corpus (auto-generated)
│ └── docs/
│ ├── CMDS_API.md # maya.cmds reference (commands, flags, patterns)
│ ├── PYMEL_API.md # PyMEL object-oriented API reference
│ ├── ARNOLD_API.md # Arnold/mtoa shaders, AOVs, render settings
│ ├── USD_API.md # Maya-USD import/export, proxy shapes, pxr API
│ └── ANTI_PATTERNS.md # Common LLM hallucinations + wrong flag names
│
├── console/ # Qt console — Maya panel + legacy standalone
│ ├── qt_compat.py # PySide2 (Maya 2023-2024) / PySide6 (2025+) shim
│ ├── maya_panel.py # Dockable workspaceControl panel for Maya
│ ├── chat_widget.py # Reusable MCPChatWidget (shared by panel & standalone)
│ ├── claude_worker.py # QThread worker — Claude CLI subprocess bridge
│ ├── server_panel.py # MCP server discovery, health checks, ServerStatusBar
│ ├── userSetup_snippet.py # Paste into Maya's userSetup.py for auto-setup
│ ├── app.py # Legacy standalone entry point (use fpt-mcp console)
│ ├── chat_window.py # Legacy standalone chat window
│ └── build_app_bundle.py # Legacy macOS .app bundle generator
│
├── tests/
├── pyproject.toml # Build config, entry point: python -m maya_mcp.server
├── reference/ # Pipeline I/O (git-ignored)
├── CLAUDE.md # Project documentation for Claude
├── WORKFLOW_GUIDE.md # Workflow guide
├── .env.example # Configuration template
└── README.mdmacOS
Autodesk Maya 2023 or later
Python 3.13 or higher (ships with Maya 2027)
Node.js v22 or higher (required by Claude Code)
Claude Code 2.x
A Claude account — Pro, Max, or API key
Ollama >= 0.17.6 — for local / free inference instead of Anthropic cloud
macOS: brew install ollama && brew services start ollama
Linux: https://ollama.com/download/linux (systemd)
Verify: ollama --version
Create the qwen3.5-mcp model (required for Ollama backends):
ollama pull qwen3.5:9b
cat > /tmp/Modelfile.qwen35mcp <<'EOF'
FROM qwen3.5:9b
PARAMETER num_ctx 16384
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER top_k 20
EOF
ollama create qwen3.5-mcp -f /tmp/Modelfile.qwen35mcpSee MODEL_STRATEGY.md for the full rationale (num_ctx bump, think: false requirement, KEEP_ALIVE tuning, KV-cache dtype)
Vision3D server for AI-powered 3D generation
git clone https://github.com/abrahamADSK/maya-mcp.git
cd maya-mcp
chmod +x install.sh
./install.shThe installer creates a virtual environment, installs dependencies, builds the RAG index, and registers the MCP server with Claude Code.
git clone https://github.com/abrahamADSK/maya-mcp.git
cd maya-mcp
cp .env.example .env
# Optional: set GPU_API_URL as a *suggested default* for Vision3D.
# It is never auto-selected — Claude will surface it when asking you
# which Vision3D URL to use, and you have to confirm it explicitly.
# Example: GPU_API_URL=http://<your-gpu-host>:8000python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# RAG dependencies (optional but recommended)
pip install chromadb sentence-transformers rank-bm25python -m maya_mcp.rag.build_indexFirst run downloads the embedding model (~570 MB, cached afterwards). The index is stored in src/maya_mcp/rag/index/ and can be committed to git.
install.sh does this for you. Step 7 of the installer detects every Maya version installed on the host, locates each version's user scripts dir, and writes an idempotent guarded block into userSetup.py that:
Adds the maya-mcp repo root to sys.path
Opens the Command Port on MAYA_PORT (from .env, default 8100) bound to localhost using sourceType='mel' with the name= kwarg form (the localhost bind keeps the port reachable only from this host — an all-interfaces bind would expose an unauthenticated arbitrary-code-execution port to the LAN; Maya 2027 also silently ignores the positional form when sourceType is specified)
Registers the MCP Pipeline menu via executeDeferred
The block is bounded by sentinel markers and reruns of install.sh are safe — the installer replaces the whole region when the markers are found.
Run ./install.sh --doctor after install to verify userSetup.py was written for every detected version (plus 4 other install-completeness checks).
Port 8100 default rationale: maya-mcp historically used port 7001, the Maya commandPort convention. On hosts with Autodesk Flame installed, port 7001 is already held by Flame's S+W Service Discovery and S+W Probe Server, and connections silently succeed against Flame instead of Maya — producing empty responses that the bridge (prior to v1.4.2) misinterpreted as successful no-ops. The default was moved to 8100 to coexist with Flame. Override via
MAYA_PORTin.envif your environment still uses 7001.
The MCP Pipeline Console panel installs itself automatically. The first time Claude connects to Maya (via maya_ping or maya_launch), the server injects the panel menu and UI through the Command Port. The panel docks next to the Attribute Editor and persists across sessions.
Add to your Maya userSetup.py:
Windows: %USERPROFILE%/Documents/maya/<version>/scripts/userSetup.py
macOS: ~/Library/Preferences/Autodesk/maya/<version>/scripts/userSetup.py
Linux: ~/maya/<version>/scripts/userSetup.py
# --- MCP Pipeline Console auto-setup ---
import sys as _mcp_sys
_mcp_root = r"/path/to/maya-mcp" # replace with your clone path
if _mcp_root not in _mcp_sys.path:
_mcp_sys.path.insert(0, _mcp_root)
import maya.utils as _mcp_utils
def _mcp_open_command_port():
try:
import maya.cmds as _mc
# Bind to localhost: an all-interfaces (":8100") bind exposes an
# unauthenticated arbitrary-code-execution port to the whole LAN.
if not _mc.commandPort("localhost:8100", query=True):
_mc.commandPort(name="localhost:8100", sourceType="mel")
except Exception:
pass
def _mcp_menu_startup():
try:
from console.maya_panel import install_menu
import maya.cmds as _mc
if not _mc.menu("mcpPipelineMenu", exists=True):
install_menu()
except Exception:
pass
_mcp_utils.executeDeferred(_mcp_open_command_port)
_mcp_utils.executeDeferred(_mcp_menu_startup)
# --- end MCP Pipeline Console ---claude mcp add maya-mcp -s user -- /path/to/maya-mcp/.venv/bin/python -m maya_mcp.serverOr for Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"maya-mcp": {
"command": "/path/to/maya-mcp/.venv/bin/python",
"args": ["-m", "maya_mcp.server"],
"cwd": "/path/to/maya-mcp",
"env": {
"GPU_API_URL": "http://your-gpu-host:8000",
"GPU_API_KEY": "your-api-key-here"
}
}
}
}maya-mcp can optionally integrate with Vision3D for image-to-3D and text-to-3D generation. This is not required for core Maya functionality.
Vision3D URL is never stored. maya-mcp does not hold any Vision3D endpoint in config files, environment presets, or hardcoded defaults. On the first Vision3D call of each MCP session:
The dispatch returns vision3d_url_required.
Claude asks you in the chat which Vision3D URL to use.
You type the URL (e.g. a local Mac MPS instance or a remote CUDA host).
Claude calls maya_vision3d(action="select_server", params={"url": "<the-url>"}).
The URL is cached in the MCP process memory until restart and used for every subsequent call of the session.
You can switch servers mid-session by calling select_server again with a different URL. No restart required.
Suggested default via GPU_API_URL — if the environment variable GPU_API_URL is set, Claude surfaces it to you as a suggested default when asking for the URL. You still have to confirm or override it explicitly; it is never auto-selected. This is the only escape hatch for pre-selector installs. GPU_API_KEY is only needed if your Vision3D server has an API key configured.
Once installed, maya-mcp is available through Claude Code or any MCP-compatible client. Open Maya, ensure the Command Port is running, and start a conversation:
You: "Create a 2x2 grid of spheres with 0.5 unit spacing"
Claude → maya_create_primitive (sphere) × 4 → maya_transform (position each) → ResultYou: "Generate a 3D model from this reference image and import it"
Claude → maya_vision3d(action='generate_image', ...) → maya_vision3d(action='poll', ...) → maya_vision3d(action='download', ...) → maya_import_file → ResultAll operations go through the safety scanner before reaching Maya. Dangerous patterns are blocked with an explanation and a safe alternative.
Variable | Description | Default |
| Maya host |
|
| Maya Command Port |
|
| Optional suggested default for the Vision3D URL prompt. Never auto-selected — Claude asks the user to confirm or override at the first Vision3D call of each session. | — |
| Vision3D API key | — |
| Verify TLS certificates for |
|
| Shape generation timeout (seconds) |
|
| Texture generation timeout (seconds) |
|
| Opt-in durable audit log of tool executions. Set to | off |
config.json (not env vars) also accepts, besides backend/model/Ollama settings:
Key | Description | Default |
| Colour-management view pinned for review/preview captures ( |
|
| Static AST validation of |
|
| Models allowed to write learned patterns to the RAG corpus; others stage candidates for review. |
|
A durable, append-only record of what the model executed in Maya, and what happened — for accountability and forensics, separate from the logs/timings.jsonl efficiency telemetry.
Off by default. It only writes when MAYA_AUDIT_LOG is set to a truthy value (1/true/yes/on). When unset there is zero perf, disk, or privacy impact and no behaviour change.
What it records. One JSON line per call to src/maya_mcp/logs/audit.jsonl: ts, tool, action, sanitised params, status (ok / error / safety_blocked / ast_rejected), plus model/backend. It covers execute_python, the dedicated mutation tools, the mutating maya_session actions, and blocked attempts (safety scan / AST dry-run rejections). Read-only actions (ping, list_scene, scene_snapshot) are excluded.
Size & privacy. For execute_python the code is stored truncated to ~2000 chars plus a SHA-256 of the full code and its length; Maya result payloads are never stored. The file rotates at 5 MB to audit.jsonl.1 (one rollover) and lives under the git-ignored logs/ dir.
Write-only. There is no MCP tool to read it (the tool count is unchanged). Inspect it with jq/grep, e.g. jq 'select(.status=="safety_blocked")' src/maya_mcp/logs/audit.jsonl.
When both maya-mcp and fpt-mcp are configured, Claude can orchestrate end-to-end VFX workflows: query ShotGrid for an asset → download reference image → generate 3D via Vision3D → import into Maya → register the publish back in ShotGrid. All from one conversation.
All three MCP servers (maya-mcp, fpt-mcp, flame-mcp) share the same architecture: hybrid RAG, HyDE, safety layer, self-learning, token tracking, and model trust gates.
Maya Command Port not responding — Verify in Maya's Script Editor: cmds.commandPort('localhost:8100', query=True). If False, run the open_command_port() snippet.
RAG search returns "index not found" — Run python -m maya_mcp.rag.build_index to build the index.
Shape inference fails immediately — Model weights may be incomplete. Check that hunyuan3d-dit-v2-0-turbo/model.fp16.safetensors (~4.6 GB) exists on the GPU server.
GPU API connection refused — Verify Vision3D is running: curl $GPU_API_URL/api/health.
maya-mcp is part of a four-component VFX pipeline. Each component has a defined role:
Repo | Role |
Controls Autodesk Flame for compositing, conform, and finishing | |
Controls Autodesk Maya for 3D modeling, animation, and rendering | |
Connects to Autodesk Flow Production Tracking (ShotGrid) for production tracking, asset management, and publishes | |
GPU inference server for AI-powered 3D generation — the remote backend for maya-mcp's image-to-3D and text-to-3D tools |
maya-mcp sits at the 3D creation stage of the pipeline. It consumes vision3d via HTTP — submitting image-to-3D or text-to-3D jobs and importing the resulting .glb files into Maya. It works alongside fpt-mcp for end-to-end workflows: query ShotGrid for an asset, generate or load reference, build the 3D asset in Maya, and register the publish back in ShotGrid. flame-mcp typically operates downstream, receiving rendered outputs from Maya for finishing.
MIT License — see LICENSE for details.
Save a validated working pattern to the RAG knowledge base.
Call this after a successful operation when search_maya_docs returned low relevance (< 60%), indicating the pattern was not well-documented. The pattern will be available in future sessions.
Model trust gates: only Opus/Fable can write directly. Other models stage candidates for review.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses model trust gates (only Opus/Fable write directly, others stage) and that patterns are available in future sessions. However, it does not mention any destructive effects or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then usage guidelines, then trust gates. No wasted words; each sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool saves to a knowledge base and an output schema exists (though not shown in input), the description covers purpose, usage, and trust model. It could mention what happens after staging or if patterns can be overwritten, but overall sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for each parameter (api, code, description), so the tool description does not need to add parameter details. The description adds contextual usage info but no new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a validated working pattern to the RAG knowledge base. It uses specific verbs ('Save', 'call') and identifies the resource, distinguishing it from sibling tools like search_maya_docs or Maya operation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use: after successful operation when search_maya_docs returned low relevance (< 60%). Also specifies alternatives (search_maya_docs) and trust gates for different model tiers, giving clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a material (lambert, blinn, phong, aiStandardSurface) with RGB color and assign it to an object.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the primary actions (create material, assign to object) but omits behavioral details such as whether existing materials are overwritten, if new nodes are always created, or any side effects. No annotations are present to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, effectively conveying the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema's rich parameter descriptions and the presence of an output schema, the description covers the essential purpose and actions. However, it could briefly mention behavior for name generation or handling duplicates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all parameters (e.g., color range, material type list). The description adds minimal extra meaning beyond restating the available types and color attribute.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a material (listing four specific types) with RGB color and assigns it to an object, distinguishing it from sibling tools like maya_create_light or maya_create_primitive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies usage for material creation and assignment but lacks differentiation or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a camera in Maya with configurable position, look-at point, and focal length.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'create a camera', which implies a mutating operation, but does not disclose side effects (e.g., new node added to scene, selection changes, or what happens to existing cameras). For a creation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that is front-loaded with the action and key configurable attributes. No extraneous information, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description need not explain return values. It adequately conveys the basic operation but lacks completeness in terms of behavioral context and parameter details. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions three of four parameters (position, look-at, focal length) but adds no detailed meaning beyond the schema's own descriptions. The name parameter is omitted. With schema description coverage reported as 0%, the description does not compensate by providing additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'create a camera' and specifies configurable attributes (position, look-at, focal length). This distinguishes it from sibling tools like maya_create_light or maya_create_primitive. However, it could explicitly state that it creates a camera node in the Maya scene.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as maya_import_file or maya_create_primitive. There is no mention of prerequisites like an open Maya scene or any context about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a light in Maya (directional, point, spot, area, ambient) with configurable intensity and color.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries full burden for behavioral disclosure. It only states 'create' without specifying side effects, required permissions, or whether the operation is reversible. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the core purpose. However, it could be slightly more structured by listing the configurable attributes more explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown) which may document return values, so the description need not explain them. However, it omits mention of position and name parameters, which are configurable. Overall adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (the tool description does not detail any parameter). Although the schema includes descriptions for each parameter, the tool description only generically mentions 'intensity and color' without adding meaning. It misses position and name, and does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the resource (a light in Maya), and specifies the supported light types (directional, point, spot, area, ambient). This distinguishes it from sibling tools like maya_create_camera or maya_create_primitive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned. The agent lacks context to choose correctly among creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a 3D primitive in Maya (cube, sphere, cylinder, cone, plane, torus) with optional position, scale, and rotation.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description carries full burden but only states basic action. Does not disclose side effects (e.g., naming conflicts, undo behavior), or behavior when position/scale/rotation are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with verb and object front-loaded. Concise, but could include a brief usage note (e.g., naming defaults).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists (not shown), so return value explanation unnecessary. Lacks guidance on integration with other tools or error handling, but sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has descriptions for each parameter (0% coverage context likely refers to top-level, not nested). Description adds no extra meaning beyond summarizing optional parameters. Baseline 3 as schema already provides meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Create', resource '3D primitive', and lists all supported types (cube, sphere, etc.). This distinguishes it from sibling tools like maya_create_camera and maya_create_light.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., maya_mesh_operation for modifications). No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import 3D files into Maya: OBJ, FBX, GLB/GLTF, Alembic ABC, Maya MA/MB, BVH mocap. With namespace, parent group, and scale options.
GLB/GLTF: uses Maya's native glTF scene parser (type='glTF Import');
if the parser is not registered or import fails, falls back to the
Vision3D sibling pattern — mesh_uv.obj + texture_baked.png next
to the GLB — building an aiStandardSurface with the texture in
baseColor and assigning it to the imported meshes.
BVH: Maya has no native BVH import, so .bvh motion-capture files are
parsed and rebuilt by the pure-Python maya_mcp.bvh_import module
(hierarchy → joints, motion → keyframes, with the per-joint
BVH→Maya rotate-order mapping handled internally). namespace and
scale_factor are forwarded to the builder; the skeleton lands under a
<namespace>:bvh_grp group. The result feeds a HumanIK retarget onto a
rigged character (mocap → generic animation library).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It details fallback behavior for GLB/GLTF, special handling for BVH (pure-Python parser, HumanIK retarget), and explains namespace/scale_factor forwarding. It doesn't cover error conditions or undo behavior, but it provides substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and options, then dives into technical details for specific formats. It is relatively concise given the complexity, though some redundancy exists (e.g., repeated mention of namespace/scale_factor in BVH section). Structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple file types with special import logic), the description covers key behaviors. It mentions output implicitly (e.g., BVH leads to HumanIK retarget) but does not discuss return values; however, an output schema exists. It could mention error handling or prerequisites, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions namespace, parent group, and scale factor, adding some context (e.g., group_under created if not exists, BVH skeleton under bvh_grp). However, it does not thoroughly describe each parameter beyond what the input schema provides. The schema itself includes descriptions, so no major gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import 3D files into Maya' and lists supported formats (OBJ, FBX, GLB/GLTF, Alembic ABC, Maya MA/MB, BVH mocap). This distinctively identifies the tool's action and resource, setting it apart from sibling tools like maya_create_primitive or maya_assign_material.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to import external 3D files) but does not explicitly state when not to use it or compare it to alternatives. It provides context for specific formats but lacks general usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute mesh operations: extrude, bevel, boolean (union/difference/intersection), combine, separate, smooth.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not mention whether operations modify the original object, create new ones, require selection, or have undo capabilities. For a mutating tool with multiple operations, this omission is critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Front-loaded with 'Execute mesh operations' and lists operations efficiently. Could include more context without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with multiple operation types (some requiring multiple objects), the description lacks behavioral context such as side effects, required object states, or parameter dependencies. Despite an output schema existing, the minimal description is insufficient for complex use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for each parameter (e.g., faces, offset, divisions). The description adds a high-level list of operations but does not explain parameter relationships or usage beyond the schema. Schema coverage is high, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes mesh operations and lists specific types (extrude, bevel, boolean, etc.). It distinguishes from sibling tools like maya_create_primitive (creation) and maya_transform (transformations), but does not explicitly name the resource (e.g., 'on a mesh object').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not specify prerequisites (e.g., object must exist) or provide when-not-to-use scenarios. Sibling tools like maya_create_primitive are for creation, but no explicit comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Maya session, query scene state, and run utility commands.
Available actions:
• ping — Check connection to Maya, return version/scene/renderer. No params needed. • launch — Open Maya and wait for Command Port to respond. No params needed. • new_scene — Create a new empty scene. Refuses if the current scene has unsaved changes; pass {"confirm": true} to discard them. • save_scene — Save the current scene. No params needed. • list_scene — List objects in the scene. Optional params: {"object_type": "mesh", "name_filter": "sphere"} • scene_snapshot — Full scene state: file, modified flag, frame range, object counts by type, renderer, plugins, resolution. No params needed. • delete — Delete objects by name (wildcards supported). Required params: {"object_name": "sphere"} • execute_python — Run arbitrary Python in Maya. Assign result to 'result' variable. Required params: {"code": "import maya.cmds as cmds; ..."} Optional: {"timeout": 60} — seconds to wait for Maya (default 10, max 600); use for long operations, progress heartbeats stream every 10s while waiting. • shelf_button — Create a shelf button with Python code. Required params: {"label": "MyBtn", "command": "print('hello')"} Optional: {"tooltip": "...", "shelf_name": "Custom", "icon_label": "MCP"} • operation_history — Read recent durable-audit records (read-only; needs MAYA_AUDIT_LOG=1). Optional params: {"limit": 50, "tool": "maya_transform", "action": "execute_python", "status": "error"} • publish — Drive the native Toolkit publisher (tk-multi-publish2) inside an engine'd Maya (launched via 'tank'). params: {"mode": "preview"|"publish", "include": ["rig"], "exclude": ["render"], "comment": "...", "timeout": 600}. 'preview' returns the collected publish tree; 'publish' activates matching tasks then validate→publish→finalize. Dependencies are captured automatically by the publish plugins. • review_turntable — Deterministic Viewport-2.0 turntable playblast → .mov (RUNS IN MAYA, long op). Frames the model, orbits 360° over [start,end] at fps, 16:9 / square pixels / overscan, offScreen (never Arnold). Required params: {"out_path": "/path.mov"} (resolve via fpt tk_resolve_path template 'movie_asset_publish' with name= so the file is {Asset}_{Task}v###.mov, e.g. DJ_Model_v001.mov — NOT 'turntable'). Optional: {"start":1,"end":100,"fps":25,"width":1920,"height":1080,"objects":[...],"focal":50,"timeout":600}. Returns the .mov plus the engine asset/task and a Version code {Asset}{Task} so the review Version is named after the task it was generated in.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behaviors: read-only vs modifying, long-running ops, error conditions, and environment requirements (e.g., operation_history needs MAYA_AUDIT_LOG=1). It does not detail all failure modes but covers the key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear purpose statement followed by a bullet list of actions. Each action is described in 1-2 concise sentences, front-loading the overall task and avoiding unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 actions with varied parameters) and the presence of an output schema, the description covers all necessary details: action behaviors, parameter specs, constraints, and prerequisites. It is self-contained and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one generic parameter (params), with 0% description coverage. The tool description compensates by exhaustively documenting required and optional parameters for every action, including types, defaults, constraints, and specific usage instructions (e.g., out_path template).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages Maya session, queries scene state, and runs utility commands. It lists 12 specific actions with detailed explanations, distinguishing itself from sibling tools that focus on specific operations like transforms or materials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for each action, including when to use them and conditions (e.g., new_scene refuses unsaved changes). It does not explicitly compare to sibling tools, but the scope is clear: session-level and utility actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an animation keyframe on an object. Allows animating translate, rotate, scale, and visibility per frame.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action. It omits behavior like whether existing keyframes are overwritten, animation curve effects, or prerequisites (e.g., object must exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence. It is front-loaded and efficient, with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple keyframe tool but incomplete: does not mention return value (output schema exists), error handling, or interpolation behavior. Could add context on attribute default or tangents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% per context, but the schema's property descriptions exist. The tool description does not add meaning beyond listing parameters; it does not explain relationships or usage order.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: 'Create an animation keyframe on an object' and lists animatable properties (translate, rotate, scale, visibility), clearly distinguishing it from siblings like maya_transform.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., maya_transform for non-keyframe transformations). The description provides no when-not or context-of-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move, rotate, or scale an object in the Maya scene.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should disclose behavioral traits. It does not mention whether transforms are absolute or relative (though 'relative' parameter exists), or any side effects like history changes. Only states the action types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, but overly sparse. Could include more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite output schema existing, the description fails to cover the tool's complexity (3 operations, 5 parameters). No mention of parameters or how to use them, making it incomplete for a transform tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover parameters fully (e.g., 'New scale [x, y, z]'), so baseline is 3. The tool description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verbs (move, rotate, scale) and identifies the resource (object in Maya scene), clearly distinguishing from sibling tools like maya_create_primitive or maya_assign_material.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, nor any conditions for move vs rotate vs scale. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture the Maya viewport as PNG/JPG image and return it for visual analysis. Does not do Arnold render — it is an instant viewport grab (<1s). Useful for visually verifying scene state, checking lighting, framing, and detecting issues.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the non-destructive nature (viewport grab, no Arnold render), instant execution, and return of an image. This provides adequate behavioral context for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the primary action and output. Every sentence adds value: first states what it does, second clarifies scope and use case. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple capture tool with no output schema, the description covers purpose, speed, and usage scenarios. It could mention more about output characteristics or limitations, but overall it is sufficient given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description offers no parameter-specific guidance. While the input schema includes descriptions, the context indicates 0% schema description coverage, so the description should compensate. It does not mention any parameter constraints or usage tips.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'capture' and the resource 'Maya viewport' with output format 'PNG/JPG image'. It distinguishes from sibling tools like Arnold render by noting it is an instant viewport grab, differentiating it from other Maya tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'verifying scene state, checking lighting, framing, and detecting issues'. It explicitly states what the tool does not do ('Does not do Arnold render') and gives a speed hint ('<1s'), guiding when to use it over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI-powered 3D asset generation via Vision3D server (requires GPU with Hunyuan3D-2).
Server selection is fully per-session and runtime-only: the first
action that needs a GPU call returns vision3d_url_required. The
LLM must ask the user for the Vision3D URL in the chat and then call
select_server with that URL. Nothing is persisted to disk — the
URL lives only in process memory until the MCP server restarts.
After selection, jobs are non-blocking: start → poll → download.
Available actions:
• select_server — Set the Vision3D server URL for the rest of the session. Required params: {"url": "http://..."}. Accepts any valid http/https URL; ask the user first. • health — Check if the selected Vision3D server is running and what GPU/models are available. No params. • generate_image — Start 3D generation from a reference image. Required params: {"image_path": "/path/to/image.png", "output_subdir": "my_asset"} Optional: {"preset": "medium", "model": "turbo", "octree_resolution": 384, "num_inference_steps": 20, "target_faces": 50000} • generate_text — Start 3D generation from a text prompt. Required params: {"text_prompt": "a medieval sword", "output_subdir": "sword"} Optional: {"preset": "medium", "model": "turbo", "octree_resolution": 384, "num_inference_steps": 20, "target_faces": 50000} • texture — Texture an existing mesh using a reference image. Required params: {"output_subdir": "my_asset"} Optional: {"mesh_filename": "mesh.glb", "image_filename": "input.png"} • poll — Check job progress (call repeatedly while running). Required params: {"job_id": "uuid-from-generate"} • download — Download completed job results. Required params: {"job_id": "uuid", "output_subdir": "my_asset"} Optional: {"files": ["textured.glb", "mesh.glb"]}
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key traits: GPU requirement, no persistence (URL only in memory), non-blocking jobs. Missing details on error handling, whether it modifies the Maya scene, or output cleanup, but still highly informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points for each action and a clear workflow. Slightly verbose (multiple paragraphs) but earns its length by covering all necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the entire pipeline from server selection to download, including async behavior. No gaps in understanding how to use this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage (schema only defines dispatch structure), the description fully documents each action's parameters with examples (e.g., 'Required params: {"image_path": ...}'). Compensates completely for lack of schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies it as 'AI-powered 3D asset generation via Vision3D server' and lists all sub-actions (select_server, health, generate_image, etc.). Distinct from sibling Maya tools (e.g., maya_create_primitive) which focus on direct scene manipulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit workflow: first select_server (ask user for URL), then start generation, poll, download. States 'jobs are non-blocking: start → poll → download' and provides required/optional params for each action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a World Labs (Marble) Gaussian-splat ENVIRONMENT from an image and load it into Maya for Arnold.
Pipeline — call the actions in order: generate → poll → download → convert → build. Credits are spent ONLY by generate with confirm=true. Call status on a work area to resume an interrupted run from disk without re-generating.
Actions:
• health — Check the WorldLabs API key + credit balance. No params. • generate — Start image→world generation. Required params: {"image": "/path.png" or "https://..."}. Optional: {"output_subdir": "world", "model": "marble-1.1"|"marble-1.1-plus", "display_name": ..., "text_prompt": ..., "confirm": true, "work_dir": "/work/worldlabs/"}. WITHOUT confirm=true it returns a cost-confirmation payload and spends NOTHING. Pass work_dir (the Toolkit work area, resolved via fpt-mcp tk_resolve_path) to write a resume sidecar so an interrupted run resumes without re-generating. • poll — Poll a generation (~5 min). Required params: {"operation_id": "..."}. • download — Download a finished world's assets to the work area. Required params: {"operation_id": "...", "dest_dir": "/work/worldlabs/"}. Optional: {"which": ["splats_full_res", "pano"]}. Updates the resume sidecar (world_id + downloaded paths). • convert — Convert the downloaded SPZ to PLY (Arnold-readable, via gsbox). Required params: {"spz_path": "/path.spz"}. Optional: {"ply_path": "/out.ply"}. • build — Load into Maya (RUNS IN MAYA): aiGaussianSplat + coloured point proxy + emission shader + eye-level centred camera, plus a fake-HDR panorama dome if given. Required params: {"ply_path": "/world.ply"}. Optional: {"pano_path": "/pano.png", "eye_height": 1.5, "proxy_step": 1, "relight": false, "draw_mode": 2, "focal": 15.0, "timeout": 300, "save_path": "/…/maya/scene.v001.ma"}. draw_mode: 2=Gaussian Splat (default, draws natively in VP2.0), 1=Point Cloud, 0=Bounding Box. focal: camera focal length in mm (default 15, wide for environments). save_path: when given (the Toolkit work-file path resolved via fpt-mcp tk_resolve_path on template maya_asset_work — Toolkit naming/versioning), the assembled scene is saved there so "open in Maya" lands the work file at the config-correct path with no manual Workfiles pick. • status — Report the resumable state of a work area (sidecar + on-disk .spz/.ply/.png). Required params: {"work_dir": "/work/worldlabs/"}. Returns where the pipeline left off (needs_generate / needs_download / needs_convert / ready_to_build).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description takes full burden and discloses key behaviors: credit spending only with confirm=true, resumability via sidecar, that build runs in Maya, and draw_mode options. It could be improved by mentioning whether operations are destructive or reversible, but overall it is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but verbose, containing several paragraphs and very detailed parameter lists. It is front-loaded with the purpose, but the length could be trimmed without losing essential information, making it less efficient for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a dispatch tool with 7 actions and no annotations, the description is mostly complete for inputs but lacks details on outputs per action (e.g., poll returns). The presence of an output schema (not shown) may mitigate this, but the description does not reference it, leaving a gap for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is generic (only action and params as any), providing 0% coverage. The description fully compensates by listing all parameters for each action with types, examples, and optional flags, adding essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating a World Labs Gaussian-splat environment from an image and loading it into Maya for Arnold. It distinguishes the tool from siblings by its specific pipeline of actions, and the name itself signals the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear pipeline order (generate → poll → download → convert → build) and gives explicit guidance on credit spending and resuming interrupted runs via status. However, it does not compare directly to sibling tools or state when not to use it, though the specialized nature makes alternatives obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Zero the session stats counters immediately.
Use at the start of a new Claude session (or a fresh debugging run) when the idle-based auto-reset has not fired — for example when two sessions happen back-to-back. Returns a confirmation line with the new reset timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses immediate zeroing, reset of counters, and return of confirmation timestamp. Missing explicit statement that it is destructive (clears data irreversibly), but 'Zero' sufficiently implies mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three precise sentences front-loaded with the action. Every sentence earns its place: action, usage context, return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and output schema existence, description fully captures behavior: immediate reset, use case, and return value. Complements schema and context signals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies. Description adds no parameter info, but none is needed as the schema is empty and coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: 'Zero the session stats counters immediately.' It uses specific verb 'Zero' and resource 'session stats counters', distinguishing it from the sibling 'session_stats' which presumably reads stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'at the start of a new Claude session (or a fresh debugging run) when the idle-based auto-reset has not fired'. Provides a concrete example (back-to-back sessions) and contrasts with alternative behavior (auto-reset).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Maya API documentation using hybrid RAG (semantic + BM25).
Call this BEFORE writing complex Maya commands, using unfamiliar flags, or when unsure about command names, return values, or syntax. Returns the most relevant documentation chunks with relevance scores.
Covers: maya.cmds, PyMEL, Arnold/mtoa, Maya-USD, and common anti-patterns. Uses HyDE query expansion + Reciprocal Rank Fusion for high precision.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the RAG technique, HyDE query expansion, and that results include relevance scores. It does not discuss side effects or rate limits, but such details are less critical for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences), front-loaded with the core purpose, and each sentence adds distinct value (what, when, what covers, how). No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and rich input schema, the description covers the tool's overall role, supported content, and advanced technique. Minor gaps (e.g., parameter details) are mitigated by the schema, so completeness is high for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% because the tool description does not mention parameters. Although the input schema itself provides detailed parameter descriptions, the low coverage means the description must compensate; it fails to do so, leaving the agent without higher-level parameter semantics from the free text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search Maya API documentation using hybrid RAG (semantic + BM25)' and lists covered domains (maya.cmds, PyMEL, etc.). It distinguishes from sibling tools that perform specific Maya actions by positioning itself as a preliminary research step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Call this BEFORE writing complex Maya commands, using unfamiliar flags, or when unsure...' This helps the agent decide when to use it, though it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show session efficiency statistics: token usage, RAG savings, patterns learned.
Call at the end of multi-step tasks or when asked about efficiency. Shows how much context was saved by RAG vs loading full documentation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, describing output details like RAG savings compared to full documentation, implying a read-only statistics tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with front-loaded purpose, usage guidance, and output detail; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and presence of output schema, description fully covers when to use and what information is provided, including specific RAG comparison.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, baseline 4. Description adds context about what statistics are displayed, compensating for lack of param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows session efficiency statistics (token usage, RAG savings, patterns learned), distinguishing it from siblings like reset_session_stats and learn_pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call at the end of multi-step tasks or when asked about efficiency, providing clear usage context, though it doesn't specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.23.0learn_patternmaya_assign_materialmaya_create_cameramaya_create_lightmaya_create_primitivemaya_import_filemaya_mesh_operationmaya_sessionmaya_set_keyframemaya_transformmaya_viewport_capturemaya_vision3dmaya_worldlabsreset_session_statssearch_maya_docssession_statsScored across 16 tools
Most tools have clearly distinct purposes, e.g., creating primitives, cameras, lights. Minor overlap exists between maya_viewport_capture and maya_session's review_turntable, but descriptions clarify differences. Overall, agents can reliably distinguish tools.
Most tools follow a `maya_<verb>_<noun>` pattern, but several tools like `learn_pattern`, `reset_session_stats`, `search_maya_docs`, and `session_stats` break the pattern by lacking the `maya_` prefix. The internal consistency is decent, but the mix is notable.
16 tools cover a broad range of Maya functionality including modeling, animation, lighting, and AI integration. While slightly on the heavier side, each tool serves a specific purpose and the set feels well-scoped for a comprehensive Maya assistant.
The tool set covers core workflows like scene creation, import, transforms, and rendering. However, gaps exist—no tools for rigging, deformers, or advanced animation curves. The inclusion of `search_maya_docs` and `learn_pattern` partially mitigates gaps, but notable operations are missing.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Cloud Blender for AI agents: scenes, assets, renders, MP4, STL, GLB — over hosted remote MCP.
