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

Goes well past the destructiveHint=true annotation: it enumerates exactly what is destroyed (the joined term), what transfers (spellings become variants, links move), irreversibility ('this cannot be undone'), and the takeDefinition override of definition/source/place. It also discloses edge-case state handling ('the result is confirmed if either was; two proposed terms stay proposed') and permission/plan gates.

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 and consequence before the finer rules; nearly every clause carries decision-relevant information. It is a single dense block that could be split into sentences for scanability, and the 'similar' aside is slightly tangential.

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 destructive, irreversible mutation with no output schema, the description covers permissions, plan gating, data migration, and edge-case status outcomes. The only real omission is what the call returns (e.g., the surviving term or confirmation state), which an agent may want before chaining calls.

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%, so the baseline is 3, but the prose adds real meaning: the asymmetry of 'from' (removed) versus 'into' (stays) is restated behaviorally, and takeDefinition is explained with its side effects on definition, source and place rather than just its default.

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 ('join one term to another of the same project when they are one notion') with a concrete example in both languages. The destructive, absorbing semantics ('the joined term is gone', its name becomes the target's variants) make it unambiguous versus near siblings like link_terms or delete_term, which are not destructive in this way.

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 the selection condition ('when they are one notion') plus prerequisites: same project, write-level membership, and an AI-inclusive plan, and points at list_terms' 'similar' flag as the discovery path. It stops short of explicitly naming the alternative to use when terms are merely related rather than identical (e.g., link_terms), so no explicit when-not routing.

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