style_rename

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

Annotations only supply readOnlyHint=false, and 'Change' is consistent with that. The description adds one genuine behavioral fact beyond the annotations: 'references follow', i.e. dependent references are updated when the id changes. It says nothing about the dry_run preview path or the expect/sha256 concurrency guard, which are the other notable behaviors.

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?

A single compact sentence with the action front-loaded and no filler. It is arguably too terse for a mutation tool, but nothing in it is wasted.

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?

No output schema exists, and the only annotation is readOnlyHint=false, so the description must carry the behavioral burden for a write operation with 6 parameters. It covers the key side effect (references follow) but omits collision/error behavior, dry_run semantics, and the expect-based pre-condition check.

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 high (83%), so the schema already documents id, doc, name, style, dry_run and expect. The 'and/or' phrasing is a small value-add, clarifying that name and id are independently optional, but the description adds little else about parameter interplay (e.g. id defaulting from name).

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 concrete verb and resource ('Change a style's display name and/or id'), so the agent knows exactly what is mutated. It does not differentiate itself from the sibling style_update, which plausibly also edits style properties, so a sibling-confusion risk remains.

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?

There is no explicit statement of when to call this instead of style_update, style_create, or style_merge, and no prerequisites (e.g. style must already exist). Usage is only loosely implied by the verb 'rename'.

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