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

Annotations only say this is a non-readonly, non-idempotent, non-destructive write; the description adds substantive behavior the annotations cannot convey: per-tenant slug uniqueness with a CONFLICT outcome, rejection of `is_default` with VALIDATION_ERROR, forced is_default=0, and automatic sort_order slotting. Error-code disclosure is exactly the context an agent needs before a mutating call.

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 dense sentence with the core action front-loaded and every clause adding a distinct constraint; nothing is filler. It is slightly overpacked with parenthetical error codes and em-dash subclauses, which costs a little readability.

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 6-param mutation with annotations covering safety and no output schema, the description supplies the failure modes, server-owned field rules, and defaulting behavior that would otherwise be invisible. Remaining gaps are the display fields (name/icon/color) and whether the created record or its id is returned.

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 6 parameters, so the description carries the burden. It adds real semantics for three of them (slug format/uniqueness/length, is_default prohibition, sort_order defaulting) but is silent on name, icon, and color, leaving half the surface undocumented anywhere.

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 opens with a specific verb and resource ('Adds a custom category to your tenant's category table') and immediately bounds scope to custom (non-seeded) categories. It explicitly names the sibling `expense_category_ensure_defaults` as the only path for seeded defaults, so an agent can distinguish the two without opening either 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?

It clearly establishes when this tool applies versus `expense_category_ensure_defaults` ('the 9 seeded defaults exist only via ...'), which is the most likely sibling confusion. It does not discuss create-vs-update routing or whether a read/list should precede creation to check slug collisions, so it stops short of explicit exclusions.

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