ass_update_style

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

With no annotations, the description carries the burden and does well: it discloses the partial-update contract, the rename side effect that always repoints lines referencing the old name, the ignored_fields safeguard for values the document's Format line cannot hold, and that changed values are reported in stored form. It omits matters like permission requirements or undo semantics, keeping it short of a 5.

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?

Front-loaded with the core semantic, then organized into alias rules and explicit Args/Returns sections. Length is justified by the 29-parameter surface and unusual alias system, though the Returns block partly duplicates the output schema.

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 29 parameters, no annotations, and an output schema present, the description covers the mutation contract, rename side effects, alias handling, and failure/edge behavior (ignored_fields) well. It is nearly complete, but the absence of any value-format guidance for the many style fields leaves a gap for a tool this wide.

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 description coverage is 0% across 29 parameters, so the description must compensate and only partly does: it explains name (case-insensitive), doc_id (None = current document), aliases (field=value pairs), and new_name's rename semantics, plus the alias-resolution mechanism mapping snake_case/ASS column names to canonical fields. The remaining ~25 style fields (color formats, integer vs float expectations for bold/italic/scale values) are left undocumented, so a great deal still has to be inferred.

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 ('Change only the fields that are given, on an existing style') and immediately establishes the partial-update semantics, which distinguishes it from a full style replacement. It also relates itself to ass_rename_style and, by implication, to ass_update_line, so an agent can separate it from siblings.

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 clear context: use it to mutate an existing style, fields you omit are left alone, and renaming via new_name behaves 'exactly like ass_rename_style'. It stops short of explicitly routing the agent ('if you only want to rename, prefer ass_rename_style'), so it lacks a true when-not statement, but the operational context is solid.

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