native_transform

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

With no annotations at all, the description carries the full burden and does meaningful work: it discloses that native Undo is retained (reversibility), that the UI must be in English/mm and the Prepare mainframe foregrounded, that optional dependencies (desktop extra, Tesseract) are required, and that request IDs are 32 hex. It omits failure/timeout behavior and whether a rejected expected_revision aborts the edit.

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?

Purpose is front-loaded in the first sentence, followed by parameter semantics then prerequisites then opt-in requirements. The terse fragments ('Requires one object/instance, English mm UI and foreground Prepare mainframe.') are dense but each sentence adds information; no filler.

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, so return-value explanation is rightly omitted, and the description covers environment gating and reversibility for a mutation tool with no annotations. But for a 6-required-parameter stateful mutation, the missing explanation of session_id/expected_revision (optimistic concurrency, stale-revision handling) is a meaningful gap.

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 coverage is 0%, so the description must teach the parameters, and it only partly does: it explains kind values (move/rotate/scale), the unit semantics of value per kind, and the target axis control including Orca's uniform lock. That is valuable, but session_id, expected_revision, and request_id are barely covered beyond the 32-hex format note — the concurrency contract around expected_revision is unexplained.

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?

States a specific verb and resource ('Edit Orca's live native gizmo') plus the distinctive verification behavior ('verify actual model pose') and undo retention. An agent knows what it does, but it never distinguishes this from the sibling project_transform_write, which appears to be the non-native equivalent.

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?

Gives real prerequisites ('Requires one object/instance, English mm UI and foreground Prepare mainframe', 'Read native_scene_read and host_bridge_status first', opt-in via ORCA_MCP_DESKTOP=1). However, it never says when to pick this over project_transform_write or what to do if the desktop bridge is unavailable, so the alternative-selection guidance is only implied.

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