mcp-for-maya

Overview Schema Source Related Servers Discussions Admin

Scene Describe

scene_describe

Read-onlyIdempotent

Fetch exact node type, attribute metadata, and connection wiring for a Maya node, enabling accurate execute_code, setAttr, and connectAttr calls.

Instructions

API-level self-description of ONE node (not spatial).

Boundary: scene_inspect answers WHERE an object is (position, bbox, neighbors); scene_nodes discovers candidate node names; scene_describe answers WHAT the node is at the API level - exact node type, per-attribute metadata, and connection wiring - so you can compose accurate execute_code/setAttr/connectAttr calls against real names.

Input Schema

Name	Required	Description
`node`	Yes	Node name (short name or long DAG path).
`attrs`	No	Attribute names to describe; None (default) lists every attribute listAttr reports UP TO the response budget (limit) - over-budget output is truncated and disclosed via attrs_truncated + total_count, never silent; narrow further with an explicit attrs list or raise limit and re-query. A named attr that does not exist aborts the whole call (attr_not_found) - no partial metadata (same contract as scene_export's missing_objects).
`limit`	No	Max items returned per face (attrs and connections). Soft default 200; a caller may relax explicitly to the hard cap 1000 (D-110) - bounds response size only, not the per-attribute query cost.
`session_key`	No	Maya session key (auto-selected if one session).
`include_values`	No	Also return value + soft_min/soft_max per attr (default False). Reading a value can trigger DG evaluation inside Maya - still read-only, but the eval may cost time on heavy graphs.
`include_connections`	No	Return connection wiring {src_plug, dst_plug, direction} (default True); the same budget applies (connections_truncated + total_connections; no cursor in v1 - narrow and re-query).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.1Sep 30, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, not open-world), but the schema text adds contract-level behavior beyond that: over-budget output is truncated and disclosed via attrs_truncated/total_count rather than silently dropped, a missing named attr aborts the whole call with attr_not_found, and include_values may trigger costly DG evaluation. These are real behavioral traits not derivable from the annotations.

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-loaded with the core purpose in the first clause, then a compact three-way boundary. Dense but every clause routes or clarifies; the parenthetical '(not spatial)' and the sibling contrast both earn their place. Slightly prose-heavy for the payload.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists and annotations are rich, so return-value explanation is not required. Given the routing ambiguity this tool sits in among scene_* siblings, the boundary paragraph supplies exactly the missing orientation an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents node, attrs, limit, include_values, include_connections and session_key in detail. The top-level description itself adds no parameter meaning beyond the boundary framing, so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb+resource ('API-level self-description of ONE node') and immediately disambiguates the concept ('not spatial'). It explicitly distinguishes itself from scene_inspect (WHERE) and scene_nodes (candidate names), so an agent can pick the right tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Boundary paragraph gives explicit when-to-use framing and names two sibling alternatives with their distinct jobs. It also names downstream tools this output feeds (execute_code/setAttr/connectAttr), tying usage to intent.

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