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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description goes further by disclosing that keywords REPLACES the whole list by default (a destructive nuance), that add/remove merge or subtract, and that matching is case-insensitive substring unless slash-wrapped for regex -- real behavioral context beyond the annotations.

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 action, then progressively layers mode behavior, keyword matching rules, and the replace-prerequisite. Four sentences, each carrying distinct information with no filler.

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 not be described. For a 4-parameter mutation tool, the description covers purpose, partial-update semantics, mode selection, matching rules, and the read-before-replace prerequisite -- nothing an agent needs to call it correctly 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 only 25% (just mode), so the description must compensate, and it does: it explains replace/add/remove semantics for keywords/name and the substring-vs-regex matching rule that appears nowhere in the schema. clusterId and the name length limits remain implied, but the high-value ambiguity (replace vs merge) is fully resolved.

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 ('Edits an existing topic cluster's name or keyword list') and clarifies the partial-update scope ('Only the fields you pass change'). An agent can immediately distinguish this from create_topic_cluster, delete_topic_cluster, and update_content_group.

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?

Explicitly routes mode selection: 'pass mode "add" or "remove" ... which is what you usually want when extending a cluster,' and names the prerequisite alternative 'Read the current list with list_topic_clusters first when replacing.' Clear context and a named sibling, though it stops short of stating cases where the tool should not be used at all.

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