Tell your agent which MCP tools cost money before it calls them twice

When we published HPSILab's MCP server, writing the tools was the easy part. The part that mattered more was telling an agent what each call does to the world.

Seven of our ten tools only read market data, so calling them twice is harmless. Two create hosted charts and reports; they can use up a quota or settle a payment, and a retry creates (and may charge for) a second one. One registers an account and sends an email. Agents retry a lot: timeouts, a second opinion, a re-plan.

What we ended up doing:

• Every tool carries all four MCP annotations, never left unset: readOnlyHint and idempotentHint are true for the seven read tools and false for the three that change something.
• The server instructions repeat this in one sentence, because not every client reads annotations.
• A test fails if any tool's annotations drift from that split.
• One tool, analyze_stock, is named as the starting point, so a model doesn't fan out across every tool for a simple question.

Annotations are hints, not enforcement; the payment checks still happen on the server. But they give a careful client a reason to ask before a second paid call.

How do you mark side effects on your tools?

hpsilab.com/?utm_source=lounge&utm_medium=community&utm_campaign=post-mcp-annotations