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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious consequences the annotations cannot express: a terms change publishes a NEW template version, and user_id records who published it. It does not mention the 422 failure mode for a foreign user_id, which lives only in the schema.

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?

Three sentences, zero filler, front-loaded with the two mutating actions before the parameter contract and the alternative tool. Every clause earns its place.

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?

An output schema exists, so return values need no explanation, and the description covers both mutation modes plus the sibling hand-off. It stops short of noting that an invalid user_id yields 422 or that the operation is idempotent, both of which matter for a destructive tool.

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?

With 50% schema coverage, the description must carry weight, and it does: it explains that custom_term_id links terms, an empty string unlinks (a non-obvious contract), and that user_id records the publisher. It does not explain the body/pathParams nesting or the full UUID id parameter, leaving some compensation to the schema.

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 ('Rename a custom template or change its linked custom terms'), and immediately separates itself from the sibling that handles YAML edits ('create-custom-template-version'). An agent can distinguish it from update-custom-term and update-template 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?

Gives an explicit when-not rule with a named alternative: 'YAML changes go through create-custom-template-version instead.' This is the exact routing information an agent needs when several update-* siblings exist.

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