Maya MCP demonstrates a critical lack of foundational schema documentation. While 71 tools are registered with basic names and short descriptions, the tool definitions visible in the source code lack proper input/output schemas, parameter type definitions, and detailed descriptions required by production standards. Descriptions are present but extremely brief (titles only, 20-50 chars), far below the 50-200 char baseline for LLM-optimized tools. No parameter descriptions, types, or constraints are visible in the provided source. The tool_metadata.py file shows only title mappings, no schema definitions. The server uses fastmcp, which should support schema registration, but the actual schemas are not present in the reviewed code, suggesting they are either missing entirely or defined elsewhere without documentation. Risk annotations (READ_ONLY, WRITE, DESTRUCTIVE, IRREVERSIBLE) are provided in the tool list but not visible as formal schema constraints or tool annotations in the code. STDIO-only transport caps overall quality severely.
No input/output schemas visible in source code. Tool definitions lack JSON Schema definitions for parameters and return types, making it impossible for LLMs to understand what inputs each tool accepts or what structure outputs follow. This is a foundational requirement for production tools.
Add complete input schemas to all 71 tools. Each parameter must have: name, type (string|number|boolean|object|array), description (50-100 chars explaining what it controls), required flag, and constraints (enum values, min/max, regex pattern where applicable). Use fastmcp's schema registration API to attach these at tool definition time.
Expand all tool descriptions from titles to 80-150 character explanations. Format: '[Verb] [resource/target]. [When to use]. [State modification info if any].' Example: 'Create a new mesh node in the current scene. Use this to add geometry before modeling operations. Modifies the scene permanently.'
Document every input parameter with a description. For parameters like 'nodes' (accept string or list?), 'type' (what values?), 'tolerance' (range?), add constraints. Example: 'nodes: Name(s) of target node(s). Accepts node name (str) or list of names. Example: 'pCube1' or ['pCube1', 'pCube2']'
Add output schema documentation to all retrieval/read tools (nodes.list, scene.info, mesh.vertices, etc.). Example for nodes.list: 'Returns array of objects with fields: {name (str), type (str), parent (str|null), selected (bool)}. Total count included for pagination.'
Implement tool annotations for destructive/irreversible operations. Use fastmcp ToolTransform or schema hints to mark: destructiveHint=true for delete operations, idempotentHint=false for script.run, readOnlyHint=true for all .get and .list tools.
Add error recovery guidance to tools that depend on state (maya.connect, script.execute). Example: 'On connection failure: check that Maya commandPort is open with `maya -port 7001`. If port is in use, restart Maya or use a different port.'
Descriptions are titles only (20-50 characters), far below the 50-200 character LLM-optimized baseline. Descriptions must explain WHAT the tool does, WHEN to use it, prerequisites, and whether it modifies state. Current descriptions lack this critical context needed for proper tool selection.
No parameter descriptions or type information visible. Parameters must include descriptions explaining what they control, constraints (enums, ranges, formats), and types. Without parameter-level documentation, LLMs cannot understand how to invoke tools correctly.
Tool annotations (readOnlyHint, destructiveHint, idempotentHint) not implemented despite risk classifications being provided in the tool list. These annotations must be formalized in schema to enable LLMs to reason about safety and side effects.
No error handling guidance visible. Tools must return actionable error messages telling LLMs what to do next, categorize errors as retryable/user-fixable/fatal, and include the invalid value and violated constraint when validation fails.
script.execute and script.run tools accept code execution but lack explicit documentation of approval/whitelist mechanisms, sandboxing, or confirmation steps. Irreversible operations should support dry-run or confirmation patterns to prevent catastrophic errors.
No output schema documentation. Tools must declare what fields are returned so LLMs can plan downstream calls and extract correct data. Without output schemas, agents cannot chain tool calls reliably.
Document pagination support for list tools (nodes.list, skin.influences, animation.get_keyframes). Add limit and offset/cursor parameters with descriptions. Return total count or next_cursor to enable agent pagination logic.
Add confirmation/approval mechanism for script.execute and script.run. Require that only whitelisted scripts execute, or implement a two-step pattern where agent calls approve_script_execution first with dry-run output, then execute_approved_script to run it.
Separate tools that combine multiple operations. Example: maya.connect likely establishes connection and validates it, split into establish_maya_connection and verify_maya_connection so agents can reason about partial failures.
Add examples to parameter descriptions showing expected formats. For scene.open: 'path: File path to Maya scene. Relative paths use Maya project. Example: 'scenes/myScene.ma' or '/absolute/path/to/scene.mb''. Avoid 'e.g.' without enum constraints; use formal types instead.
Implement idempotency guards for write operations. Tools like scene.save should return 'already saved' if no changes occurred, preventing the LLM from retrying unnecessarily. Document idempotency guarantees in descriptions.
Return chaining IDs and references in responses. If modeling.create_polygon_primitive creates a mesh, return {node_name, node_id, selected (bool)} so the agent can immediately use the result with modeling.extrude_faces without a lookup call.
Add a 'dry_run' or 'preview' mode to destructive operations (modeling.delete_faces, nodes.delete, animation.delete_keyframes). Return what would be affected, then require a second call with confirm=true to execute.
Document Maya-specific constraints in parameter descriptions. Example for attributes.set: 'attribute_value must match the attribute's type (float, int, str, bool). Numeric attributes accept min/max constraints defined in Maya, values outside range are clamped.'
Validate inputs early and return clear errors. Instead of a 500 error, return: {'error': 'Invalid node type: got "foo", must be one of: mesh, transform, camera, light, ...'}. Include the failed input value and valid alternatives.