set_typed_attribute

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool can run in preview mode or actually set, and it exposes a critical rule about overwrite and type immutability. Still, it does not say what 'preview' does, whether the operation is reversible, what side effects occur on the stage, or how command_id and idempotency_key affect execution.

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 two sentences with no filler, front-loading the core action and then immediately stating the key constraint. Every clause contributes either to identifying the tool or to preventing a common misuse, so it earns high marks for conciseness.

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?

This is a 9-parameter tool with no annotations and zero schema descriptions, yet the description covers only a fraction of the operational context. It does not explain preview behavior, accepted type_name values, how to construct value, the meaning of custom, or the role of idempotency_key. The presence of an output schema slightly reduces the need to describe return values, but the overall definition is too sparse for reliable invocation.

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?

The schema has 0% parameter description coverage, so the description must compensate for nine parameters, but it only sheds light on preview, overwrite, and type_name. Required fields like prim_path, attribute, and value are not explained at all, nor are custom, command_id, or idempotency_key. The minimal mention of 'typed' hints at type_name but leaves the agent guessing about valid values and formatting.

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 uses a specific verb pair ('preview or set') and a concrete resource ('finite, explicitly typed USD attribute'), making the primary purpose unmistakable. It also distinguishes itself from the read-only sibling get_typed_attribute and from other setters by focusing on typed attributes and the overwrite constraint.

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?

It mentions an important condition—'Existing attributes require overwrite=true and cannot change type'—which implicitly tells the agent when overwrite must be used. However, it does not explicitly state when to prefer this tool over alternatives such as get_typed_attribute or other attribute-related tools, nor does it describe scenarios where the tool should not be used.

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