The present API/SPI for handling tooltips has certain difficulties:
1) As the tooltips are registered as annotations (org.openide.text.Annotation)
it's not clear (especially for new developers) how should it whole work.

2) Tooltip evaluation does not run in AWT thread.
 The Annotation is registered to annoatable which is a document. However often
the tooltip annotations need an access to component as well. The annotations
processing does not run in AWT (historical reasons - since the primary clients
of the tooltips were using JMI that might lock AWT thread for rather long time).
However access to a pane needs to be done in AWT (e.g. now there is even an
assertion in impl of EditorCookie.getOpenedPanes() that prohibits call outside AWT).
Such clients need first reschedule from RP to AWT to get the pane and then
eventually reschedule back from AWT into an RP to finish potentially long
computation.
IMHO it would be better to invoke in AWT primarily but let the computation to
use another thread eventually. The same approach is used e.g. in Code Completion
API.

3) The context information might be enhanced. There should be a final class
providing all the necessary context where the tooltip is being evaluated
(including the editor pane).

4) The unified registration of tooltip SPI providers through the MimeLookup
could be used to sync with other editor APIs and provide global/mime-specific
granularity.