I’m getting old. And I forget things. 
So oftentimes when revisiting my mappings in Agent I wonder what some keys and their assigned key combos do, especially if I don’t use them as often as initially thought.
Having the possibility to add notes to each mapping would go a long way for people like me.
You know you can create macros, right? 
But it takes many more clicks to create a macro for every key binding instead of directly assigning a key combo in the key map, just to get the added benefit of being able to name it.
Or am I misunderstanding your suggestion? 
You understand it fine.
¯\(ツ)/¯
I created a separate document where I keep my notes for the keymap.
I think the question is a good one. One nice solution could be to allow tooltips in Agent. The content of a tooltip can then be defined in the macro code with a special string, e.g.
//TT This is the tooltip text. \n That is the second line of the tooltip.
For all non-macro keys a field which allows to define the tooltip could be added.
And then the tooltip would be displayed in Agent, when hovering the mouse over a key (longer than half a second or something like that).
@rpnfan lovely, your mock-ups perfectly picture what I had in mind. 
I created a request on Github Add option for tooltips #2289.
Unfortunately the response was
I think this feature is too niche and isn’t worth the effort and the extra UI space, but I keep it open so others can see and upvote it.
TL;DR: Vote for that or a similar feature, see link to Github above! 
I think that the UI space in agent is well worth it. I can not comment on the efforts to implement that. But I think that there will be many UHK users who will like and benefit from such a feature.
Example (note that line-breaks are a must for the tooltip):
tap: Y
hold: redo (Ctrl-Y)
double tap hold: undo (Ctrl-Z)
For example when you assign a program to be launched (TheCoolestProgramEver) to a key combination, which would be cumbersome to use, like Shift-Ctrl-Win-Alt-C and assign this shortcut to a cluster key for example. Without the tooltip that would just show the cryptic assignments, but it would not be clear that TheCoolestProgramEver is lauched, when pressing that key. A tooltip would be highly beneficial. In that case a name macro could be a workaround, but only when the key has no second function. Otherwise the space in Agent will be too limited. So for that example the tooltip would show:
TheCoolestProgramEver
Can you tell directly what those keys do in my layout (US international)?
1-key: ¹ (superscript 1)
2-key: ²
3-key: ³
5-key (which is at the 4th position here): €
4-key (which is at the 5th position here): £
That is just making use of the standard OS English layout and already everything than self-explaining in Agent IMO.
Long story short, let us vote for that or a similar feature, see link to Github above!
Finally, it does not have to be the suggested implementation. I think that would work nicely, but another or additional option could be to allow naming what is shown in Agent. In the example of point 4 you would then just directly print the relevant character. I know the macro workaround is an option, but it is much extra work and also not nice, because technically it is a macro, but in reality that will be just a simple key-combination. So the macro-star symbol is IMO irritating for that kind of keys.
In addition to the tooltips we would ‘need’ an option to allow to define what is shown on a key in Agent.
I was just tinkering with my layout and realized that tooltips will be needed, but in many cases (those which could be worked around by creating a macro) should directly visible. So with my example in the last post (point 4) one should be able to define the text shown on any key, without the need to hover over it. Then in addition the tooltips still are needed for more complex keys or for extra help or explanations. 
There’s too much information to show and too little space on keys. I can think of a discrete triangle indicator in the corner of keys containing notes to show the presence of notes:
The triangle marker would be placed underneath key mapping content not to cover it.
Notes would be shown as tooltips upon hovering the keys.
I like the triangle. I disagree that there is no space for custom infos.
When looking in Agent there is quite a lot of text shown on each key.
The Oryx configurator allows custom text for example. When that would allow two lines it would be perfect. With 10 chars on one line only it is indeed a bit limited.
No, I would very likely also annotate keys with macros.
No, for sure for any type of key actions, not plain key presses. Especially for macros, where you are more likely to have a second, third or “wild” action.
