set_viewport_state

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

Annotations already establish idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the bar is lower. The description adds the key disclosure that the mutation targets transient editor view state rather than persisted entity data, effectively delimiting the write footprint and assuring non-persistence of effects. This complements the annotations and does not contradict them.

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?

Two sentences, roughly 30 words, front-loaded with the action and resource enumeration followed by the scoping caveat. Every sentence earns its place and there is 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?

Reasonable for a state-setter whose safety profile is carried by annotations. The main gaps are uncovered parameter interactions (orthoHeight only meaningful with orthographic projection), what an all-optional empty call does, and no acknowledgment of the read counterpart query_viewport_state for verification — though since no output schema exists, silence on return values is acceptable.

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?

With only 11% schema description coverage (only cameraId is documented in-schema), the description must compensate. It maps parameter groups to aspects — 'camera transform' covers position/rotation/cameraId/orthoHeight, 'grid' covers the nested grid object, 'expanded state' covers expanded — which adds some meaning. However, per-parameter semantics remain undefined: rotation units, orthoHeight's relevance only to orthographic projection, the meaning of grid size vs divisions, and the behavior of an empty call.

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 names a specific verb ('Set') and resource with an explicit enumeration of covered aspects: camera transform, projection, grid, bones, icon size, and expanded state. The second sentence adds a useful boundary by ruling out entity persisted enabled state, preventing a plausible category confusion. It does not explicitly name sibling tools, but the set/query verb split makes the contrast with query_viewport_state reasonably evident.

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 offers one meaningful exclusion — 'not an entity's persisted enabled state' — which steers agents away from a real misuse scenario. However, it gives no explicit when-to-use guidance and does not route among the tightly related viewport siblings (query_viewport_state, set_viewport_visibility, focus_camera, focus_viewport), leaving usage largely implied.

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