It can be tedious to write code like this:
set MyVariable [SomeCommand $MyVariable]
By using the @ designator, you mark an argument as the name of an in/out variable. An in/out variable both gives input and takes output. This simplifies, for example, the above code to this:
SomeCommand @MyVariable
MyVariable will now have been modified.
When can you use @? If you see an argument named XxxVariable (e.g. ListVariable, StringVariable, etc.) in the documentation then you can use @ for that argument. Arguments of the form XxxVariable can take either a normal value or the name of a variable to read/write, prefixed by @.
For example, take the command DoubleChop. It has an argument StringVariable. That means you can pass in either the name of a variable or a value. You can do both:
% puts [DoubleChop "{something}"]
something
... and you can do ...
set MyVar "{something}"
DoubleChop @MyVar
puts $MyVar
something
Note that currently all commands where you can use @ will also return the value of the modified variable as well. However, this is not a guarantee for the future since there may be instances with multiple in/out variables or we may want to use a return code, etc. For now, it is best to think of the @ designator as an experimental bonus feature that adds convenience to some commands.
Currently there is not anything set up for a situation where (1) there is an argument of the form @xxx and (2) the command code treats that as an in/out variable name but (3) the caller intends for it to be a normal value. In other words, there is currently no way to escape @ if you need to. We will address that in the near future.