feat: MCP tool annotations, typed write outputs, and documentation (#54)

* feat: add MCP tool annotations and typed write outputs

Support MCP ToolAnnotations (ReadOnlyHint, DestructiveHint, IdempotentHint,
OpenWorldHint) with three-level override chain: per-registration, toolkit-level,
and defaults. Add typed output structs for write tools and ListConnections.

Ref: txn2/mcp-data-platform#102

* docs: document MCP tool annotations and typed write outputs

Update CLAUDE.md, README, doc site (tools reference, API reference,
configuration, quickstart, MCP protocol concepts) with annotation
override API, default annotation table, and write tool output types.

Ref: txn2/mcp-data-platform#102

Author: cjimti

CLAUDE.md

@@ -139,6 +139,19 @@ Tool descriptions can be customized at three levels of priority:
 
 Descriptions can also be set via config file (`toolkit.descriptions` section) or the `Descriptions` field in `server.Options`.
 
+## Annotation Overrides
+
+MCP tool annotations (behavior hints per the MCP specification) follow the same three-level priority:
+
+1. **Per-registration** (highest): `toolkit.RegisterWith(server, tools.ToolSearch, tools.WithAnnotation(&mcp.ToolAnnotations{...}))`
+2. **Toolkit-level**: `tools.NewToolkit(client, cfg, tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{...}))`
+3. **Default**: Built-in annotations from `pkg/tools/annotations.go`
+
+Default annotations for all 19 tools:
+
+- **Read tools** (12): `ReadOnlyHint: true`, `IdempotentHint: true`, `OpenWorldHint: false`
+- **Write tools** (7): `DestructiveHint: false`, `IdempotentHint: true`, `OpenWorldHint: false`
+
 ## Extensions Package (`pkg/extensions/`)
 
 Optional middleware and config file support. All extensions are opt-in.

README.md

@@ -92,6 +92,20 @@ toolkit := tools.NewToolkit(datahubClient, tools.Config{},
 )
 ```
 
+#### Customizing Tool Annotations
+
+Override [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) (behavior hints for AI clients):
+
+```go
+toolkit := tools.NewToolkit(datahubClient, tools.Config{},
+    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{
+        tools.ToolSearch: {ReadOnlyHint: true, OpenWorldHint: boolPtr(true)},
+    }),
+)
+```
+
+All 19 tools ship with default annotations: read tools are marked `ReadOnlyHint: true`, write tools are marked `DestructiveHint: false` and `IdempotentHint: true`.
+
 #### Extensions (Logging, Metrics, Error Hints)
 
 Enable optional middleware via the extensions package:

docs/concepts/mcp-protocol.md

@@ -57,6 +57,7 @@ Tools are functions that AI assistants can call. Each tool has:
 | Name | Unique identifier |
 | Description | What the tool does |
 | Input Schema | Parameters the tool accepts |
+| Annotations | Behavior hints (read-only, destructive, idempotent) |
 | Handler | Function that executes the tool |
 
 Example tool definition:
@@ -86,6 +87,19 @@ Example tool definition:
 }
 ```
 
+### Tool Annotations
+
+Tool annotations are optional metadata that describe a tool's behavior to AI clients. mcp-datahub sets annotations on all 19 tools:
+
+| Annotation | Description |
+|------------|-------------|
+| `ReadOnlyHint` | Tool only reads data (all 12 read tools) |
+| `DestructiveHint` | Tool may destructively update (false for all write tools) |
+| `IdempotentHint` | Repeated calls produce the same result (all tools) |
+| `OpenWorldHint` | Tool interacts with external entities beyond the server (false for all tools) |
+
+MCP clients can use these hints to make informed decisions, such as auto-approving read-only tools or prompting for confirmation before write operations.
+
 ### Transport
 
 MCP supports multiple transport mechanisms:

docs/library/quickstart.md

@@ -108,6 +108,20 @@ toolkit := tools.NewToolkit(datahubClient, tools.Config{},
 )
 ```
 
+## With Annotation Overrides
+
+Customize MCP tool annotations (behavior hints for AI clients):
+
+```go
+toolkit := tools.NewToolkit(datahubClient, tools.Config{},
+    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{
+        tools.ToolSearch: {ReadOnlyHint: true, OpenWorldHint: boolPtr(true)},
+    }),
+)
+```
+
+All tools ship with sensible defaults (read tools marked read-only, write tools marked non-destructive and idempotent). See the [Tools API Reference](../reference/tools-api.md#withannotations) for the full annotation API.
+
 ## With Extensions
 
 Enable built-in middleware for logging, metrics, and error hints:

docs/reference/configuration.md

@@ -180,6 +180,34 @@ Description priority (highest to lowest):
 2. Toolkit-level override via `WithDescriptions()`
 3. Built-in default description
 
+## Annotation Overrides
+
+Customize [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) (behavior hints for AI clients):
+
+```go
+toolkit := tools.NewToolkit(datahubClient, tools.Config{},
+    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{
+        tools.ToolSearch: {ReadOnlyHint: true, OpenWorldHint: boolPtr(true)},
+    }),
+)
+```
+
+Or override a single tool at registration time:
+
+```go
+toolkit.RegisterWith(server, tools.ToolSearch,
+    tools.WithAnnotation(&mcp.ToolAnnotations{ReadOnlyHint: true}),
+)
+```
+
+Annotation priority (highest to lowest):
+
+1. Per-registration override via `WithAnnotation()`
+2. Toolkit-level override via `WithAnnotations()`
+3. Built-in default annotations
+
+All 19 tools ship with defaults: read tools are `ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: false`; write tools are `DestructiveHint: false, IdempotentHint: true, OpenWorldHint: false`.
+
 ## Extensions Configuration
 
 The `extensions` package provides built-in middleware and config file support.

docs/reference/tools-api.md

@@ -153,6 +153,61 @@ toolkit.RegisterWith(server, tools.ToolSearch,
 2. Toolkit-level `WithDescriptions()` map
 3. Built-in default description (lowest)
 
+### WithAnnotations
+
+Overrides MCP tool annotations at the toolkit level.
+
+```go
+func WithAnnotations(anns map[ToolName]*mcp.ToolAnnotations) ToolkitOption
+```
+
+**Example:**
+
+```go
+toolkit := tools.NewToolkit(datahubClient, config,
+    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{
+        tools.ToolSearch: {ReadOnlyHint: true, OpenWorldHint: boolPtr(true)},
+    }),
+)
+```
+
+### WithAnnotation
+
+Overrides the annotations for a single tool at registration time.
+
+```go
+func WithAnnotation(ann *mcp.ToolAnnotations) ToolOption
+```
+
+**Example:**
+
+```go
+toolkit.RegisterWith(server, tools.ToolSearch,
+    tools.WithAnnotation(&mcp.ToolAnnotations{ReadOnlyHint: true}),
+)
+```
+
+**Annotation Priority:**
+
+1. Per-registration `WithAnnotation()` (highest)
+2. Toolkit-level `WithAnnotations()` map
+3. Built-in default annotations (lowest)
+
+### DefaultAnnotations
+
+Returns the default annotations for a tool by name. Returns nil for unknown tool names.
+
+```go
+func DefaultAnnotations(name ToolName) *mcp.ToolAnnotations
+```
+
+**Default Annotations:**
+
+| Tool Category | ReadOnlyHint | DestructiveHint | IdempotentHint | OpenWorldHint |
+|---------------|:------------:|:---------------:|:--------------:|:-------------:|
+| Read tools (12) | `true` | _(default)_ | `true` | `false` |
+| Write tools (7) | `false` | `false` | `true` | `false` |
+
 ## Tool Names
 
 Available tool name constants:
@@ -261,6 +316,74 @@ Creates an error result.
 func ErrorResult(msg string) *mcp.CallToolResult
 ```
 
+## Write Tool Output Types
+
+Write tools return typed output structs as the second return value from their handler functions. These provide structured access to operation results.
+
+### UpdateDescriptionOutput
+
+```go
+type UpdateDescriptionOutput struct {
+    URN    string `json:"urn"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+```
+
+### AddTagOutput / RemoveTagOutput
+
+```go
+type AddTagOutput struct {
+    URN    string `json:"urn"`
+    Tag    string `json:"tag"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+
+type RemoveTagOutput struct {
+    URN    string `json:"urn"`
+    Tag    string `json:"tag"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+```
+
+### AddGlossaryTermOutput / RemoveGlossaryTermOutput
+
+```go
+type AddGlossaryTermOutput struct {
+    URN    string `json:"urn"`
+    Term   string `json:"term"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+
+type RemoveGlossaryTermOutput struct {
+    URN    string `json:"urn"`
+    Term   string `json:"term"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+```
+
+### AddLinkOutput / RemoveLinkOutput
+
+```go
+type AddLinkOutput struct {
+    URN    string `json:"urn"`
+    URL    string `json:"url"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+
+type RemoveLinkOutput struct {
+    URN    string `json:"urn"`
+    URL    string `json:"url"`
+    Aspect string `json:"aspect"`
+    Action string `json:"action"`
+}
+```
+
 ## Integration Package
 
 The `integration` package provides interfaces for enterprise integration.

docs/server/tools.md

@@ -2,6 +2,19 @@
 
 mcp-datahub provides 19 MCP tools for interacting with DataHub (12 read + 7 write).
 
+## Tool Annotations
+
+All tools include [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) that describe their behavior to AI clients:
+
+| Hint | Read Tools | Write Tools | Description |
+|------|:----------:|:-----------:|-------------|
+| `ReadOnlyHint` | `true` | `false` | Whether the tool only reads data |
+| `DestructiveHint` | _(default)_ | `false` | Whether the tool may destructively update |
+| `IdempotentHint` | `true` | `true` | Whether repeated calls produce the same result |
+| `OpenWorldHint` | `false` | `false` | Whether the tool interacts with external entities |
+
+These annotations help MCP clients make informed decisions about tool invocation (e.g., auto-approving read-only tools). Library users can override annotations per-tool or per-toolkit; see the [Tools API Reference](../reference/tools-api.md#withannotations).
+
 ## Multi-Server Support
 
 All tools accept an optional `connection` parameter to target a specific DataHub server in multi-server environments. Use `datahub_list_connections` to discover available connections.

pkg/tools/annotations.go

@@ -0,0 +1,64 @@
+package tools
+
+import "github.com/modelcontextprotocol/go-sdk/mcp"
+
+// boolPtr returns a pointer to a bool value.
+func boolPtr(b bool) *bool {
+	return &b
+}
+
+// defaultAnnotations holds the default annotations for each built-in tool.
+// These follow the MCP specification:
+//   - ReadOnlyHint (bool, default false): tool does not modify state
+//   - DestructiveHint (*bool, default true): tool may destructively update
+//   - IdempotentHint (bool, default false): repeated calls produce same result
+//   - OpenWorldHint (*bool, default true): tool interacts with external entities
+var defaultAnnotations = map[ToolName]*mcp.ToolAnnotations{
+	// Read-only tools
+	ToolSearch:           {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetEntity:        {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetSchema:        {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetLineage:       {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetColumnLineage: {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetQueries:       {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetGlossaryTerm:  {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolListTags:         {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolListDomains:      {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolListDataProducts: {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolGetDataProduct:   {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolListConnections:  {ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+
+	// Write tools
+	ToolUpdateDescription:  {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolAddTag:             {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolRemoveTag:          {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolAddGlossaryTerm:    {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolRemoveGlossaryTerm: {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolAddLink:            {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+	ToolRemoveLink:         {DestructiveHint: boolPtr(false), IdempotentHint: true, OpenWorldHint: boolPtr(false)},
+}
+
+// DefaultAnnotations returns the default annotations for a tool.
+// Returns nil for unknown tool names.
+func DefaultAnnotations(name ToolName) *mcp.ToolAnnotations {
+	return defaultAnnotations[name]
+}
+
+// getAnnotations resolves the annotations for a tool using the priority chain:
+// 1. Per-registration override (cfg.annotations) — highest priority
+// 2. Toolkit-level override (t.annotations) — medium priority
+// 3. Default annotations — lowest priority.
+func (t *Toolkit) getAnnotations(name ToolName, cfg *toolConfig) *mcp.ToolAnnotations {
+	// Per-registration override (highest priority)
+	if cfg != nil && cfg.annotations != nil {
+		return cfg.annotations
+	}
+
+	// Toolkit-level override (medium priority)
+	if ann, ok := t.annotations[name]; ok {
+		return ann
+	}
+
+	// Default annotations (lowest priority)
+	return defaultAnnotations[name]
+}