Are Your Tooltips Pointing You in the Right Direction?

Abstract

AI can confidently generate solutions, but are they truly right for your application, or just technically correct? In this post, I share how a simple question about tooltips led me through three levels of inquiry: is it useful, is it consistent, and is it the right long-term solution? If you care about building interfaces that actually help users (and developers), this one is for you.

---

Built by AI, Guided by Me

Our entire codebase for this application was built using AI tools — including Cursor and a variety of large language models (LLMs) — with me guiding the architecture, design, and decisions along the way.

The First Question: Is It Useful?

While refining a knowledge base page, I noticed several metrics and elements lacked explanation.
So I asked the AI agents a question:
Should we add tooltips here so users better understand what they are looking at?
The response came back quickly — and confidently — with helpful tooltips explaining categories, priorities, resolution times, and similarity scores. That felt like a step in the right direction.

The Second Question: Is It Consistent?

But then I wondered:
Are we consistent with how we implement tooltips elsewhere in the application?
It turned out we were not. Different parts of the codebase used slightly different patterns. Some components wrapped themselves in a local provider — meaning the tooltip functionality was defined and scoped just to that module or section — while others assumed a global provider, where the tooltip setup applied to the entire application.
A “provider” in this context is simply a bit of code that enables certain functionality. If it is “local,” it only affects one part of the app. If it is “global,” it ensures that functionality works everywhere in the app without repeating yourself.

The Third Question: Is It Right and Correct for the Long Term?

Even after making it consistent, I asked myself again:
Is this the right implementation for long-term maintenance?
That distinction is important. A solution can be correct today — it works, it solves the immediate problem — but it might still cause trouble later, making future changes harder, creating technical debt, or complicating onboarding for new developers. So I aligned everything to a single global provider, simplifying the developer experience and ensuring consistent behavior across the app.
In this case, moving to a single global provider was both correct and right for the long term: it eliminated repetition, improved performance slightly, and ensured that any future tooltip enhancements would propagate everywhere without extra work.

Technically Correct, But Not Useful

This reminded me of a joke I love — because it feels so relevant to what we do in software development:

A man is flying in a helicopter and realizes he is lost.
He spots a man below and shouts:

“Excuse me, can you help me? I promised a friend I would meet him an hour ago, but I don’t know where I am!”

The man replies: “You are in a helicopter hovering approximately 30 feet above the ground. You are between 40 and 41 degrees north latitude and between 59 and 60 degrees west longitude.”

“You must work at <well-known company in the Pacific Northwest United States>,” says the pilot.

“I do,” replies the man. “How did you know?”

“Well,” says the pilot, “everything you told me is technically correct, but it is of no use to me!”

That is exactly the kind of trap AI — and even experienced engineers — can fall into. It is not enough for a solution to be fast or technically correct. It has to actually help you get where you need to go and continue to work well as your needs evolve. And yes, there is a version of the joke that also points the finger at management too!

My Recommendation

Whenever I get an answer from AI or another engineer, I pause and ask myself:

• Is it useful here and now?
• Is it consistent across the application?
• Is it the right solution for the long term?

I recommend every developer and decision-maker ask these questions, regardless of how confidently the answer was delivered. Confidence and correctness are not the same, and “right” requires thought beyond what the AI, or even we, might initially suggest.
If you have your own “helicopter” moments — or want to make sure your tooltips (and more) are pointing users in the right direction — feel free to contact me if you’d like to discuss more or share your experiences.

Matt Pitts, Sr Architect