Resolved style of a node

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavior: it flattens style, translates to CSS, and names shared styles/variables that resolve within the file. This goes beyond annotations by explaining the resolution behavior and output format, though it does not detail every output field.

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, information-dense sentence that front-loads the purpose and lists key attributes. It is not overly verbose, though it is longer than ideal. Structure is logical and everything earns 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's complexity (many style aspects, parent-layout behavior), the description covers a broad range of output features. It explains the translation to CSS and the naming of shared styles. The includeRuns parameter is documented in the schema, so the description need not mention it. Overall, it is complete for an agent to understand the tool's scope.

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 100%, so all parameters are documented. The description does not add substantial meaning to file, guid, or includeRuns beyond what the schema already provides; it focuses on output content rather than parameter semantics. Thus, 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's purpose: returning the flattened style of one node, translated to CSS terms. It lists specific style aspects (fills, strokes, effects, corner radii, typography, auto-layout) and even parent layout behavior, making it distinct from siblings like fig_node or fig_text which serve different purposes.

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 usage by stating it produces the style 'shaped for writing code', which suggests when to use it (e.g., when generating CSS). However, it does not explicitly contrast with siblings or state when not to use it. This is a minor gap, but the purpose is clear enough that an agent can infer appropriate usage.

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