Introduce semantic hints for side-effects of tools

[khushalsagar]

Forking from #45 (comment). MCP already has a concept of annotations to provide deterministic hints of the side-effects a tool execution can have. These are helpful for Agents to decide whether a tool should be used in a specific context. And for users to express preferences of the type of actions they want to allow an Agent to take. As an example, readOnlyHint could be used if the user wants an Agent to be in "conversational mode" only.

Thanks @victorhuangwq for bringing this up!

[MiguelsPizza]

MCP annotation spec for reference

Annotations for WebMCP are much more exciting than they are for traditional MCP IMO. The ability to give annotations enforceable semantics in a web standard is something I wish we had in MCP. A third party (UA) enforcing middleware on tool calls is something unique to WebMCP and is something we should definitely explore.

For example, the browser could allow concurrent execution of tools marked as readOnly while serializing those marked destructive.

The current spec of MCP is largely focused on the server side (tool provider) with almost no opinions enforced on the client side (tool caller). Annotations are 100% up to the client to handle (or not handle).

[victorhuangwq]

One thing I would clarify here, it’s not just about adding semantic hints. What would make hints useful is having a standardized set of hints with well-defined, agreed-upon meanings, so they’re precise and not open-ended.