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

Annotations only declare the safety profile (readOnly=false, destructive=true, idempotent=true); the description goes well beyond by explaining in-place update semantics ('only the fields you send change'), that the key and semantic role are immutable, that archiving is reversible and 'nothing is deleted', that `order` is atomic, and that changes apply immediately. This is exactly the extra behavioral context the annotations cannot convey.

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 verb/resource statement, then cleanly sectioned into update semantics, ordering, archiving, and a 'When to use' + 'Example' block. It is long for a tool description and overlaps noticeably with the already-rich schema text, which keeps it out of 5 territory.

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?

For a 9-parameter, high-consequence mutation tool, the description covers the update-vs-create distinction, the semantic_role prerequisite, the atomic order contract, reversibility, and immediacy of effect. An output schema exists and the annotations carry the safety profile, so nothing an agent needs before invoking is missing.

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% and the parameter descriptions are themselves very detailed (color null-clearing, complete order list, position-vs-order, semantic_role per field), so the prose largely restates the schema rather than adding syntax or format meaning. The one genuine addition is the worked example tying label+semantic_role together, which is why this sits at the baseline 3 rather than lower.

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?

Opens with a specific verb set (add, relabel, recolor, reposition, archive, reorder) applied to a precisely scoped resource: the values of a built-in pick-list field, with concrete examples (account.lifecycle_stage, opportunity.type). An agent can distinguish this from sibling field tools like define_field or update_field without opening any schema.

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 'When to use' block gives clear triggering context (an admin wants a new, renamed, recolored, reordered or retired value) and repeats the semantic_role requirement for behavior fields. It also clarifies the order-vs-position split. It never names a sibling alternative (e.g. update_field, archive_field) or an exclusion, so it stops short of a 5.

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