Update README

bump: version 0.49.2 → 0.50.0
Merge pull request #387 from cbcoutinho/feat/add-mcp-tool-annotations
2025-12-11 12:59:56 +00:00 · 2025-12-11 12:58:08 +00:00 · 2025-12-11 13:57:35 +01:00 · 2025-12-11 13:50:55 +01:00 · 2025-12-11 12:45:02 +01:00 · 2025-12-10 12:56:34 +01:00
27 changed files with 1328 additions and 126 deletions
@@ -33,7 +33,7 @@ jobs:

      - name: Run Claude Code Review
        id: claude-review
-        uses: anthropics/claude-code-action@6337623ebba10cf8c8214b507993f8062fd4ccfb # v1
+        uses: anthropics/claude-code-action@f0c8eb29807907de7f5412d04afceb5e24817127 # v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
@@ -32,7 +32,7 @@ jobs:

      - name: Run Claude Code
        id: claude
-        uses: anthropics/claude-code-action@6337623ebba10cf8c8214b507993f8062fd4ccfb # v1
+        uses: anthropics/claude-code-action@f0c8eb29807907de7f5412d04afceb5e24817127 # v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

@@ -42,7 +42,7 @@ jobs:
          VECTOR_SYNC_SCAN_INTERVAL: "5"

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5

      - name: Wait for Nextcloud to be ready
        run: |
@@ -20,7 +20,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
      - name: Install uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
      - name: Install Python 3.11
        run: uv python install 3.11
      - name: Build
@@ -11,7 +11,7 @@ jobs:
    steps:
      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
      - name: Check format
        run: |
          uv run --frozen ruff format --diff
@@ -56,7 +56,7 @@ jobs:
          up-flags: "--build"

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5

      - name: Install Playwright dependencies
        run: |
@@ -1,3 +1,25 @@
+## v0.50.0 (2025-12-11)
+
+### Feat
+
+- add MCP tool annotations for enhanced UX
+
+### Fix
+
+- address PR review feedback
+
+## v0.49.2 (2025-12-09)
+
+### Fix
+
+- Update lockfile
+
+## v0.49.1 (2025-12-09)
+
+### Fix
+
+- Revert mcp version <1.23
+
 ## v0.49.0 (2025-12-08)

 ### Feat
@@ -56,6 +56,68 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
  - Pass-through (default): Simple, stateless (ENABLE_TOKEN_EXCHANGE=false)
  - Token exchange (opt-in): RFC 8693 delegation (ENABLE_TOKEN_EXCHANGE=true)

+### MCP Tool Annotations (ADR-017)
+
+**All tools MUST include annotations** following these patterns:
+
+```python
+from mcp.types import ToolAnnotations
+
+# Read-only tools (list, search, get)
+@mcp.tool(
+    title="Human Readable Name",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True,  # Nextcloud is external to MCP server
+    ),
+)
+
+# Create operations
+@mcp.tool(
+    title="Create Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Creates new resources each time
+        openWorldHint=True,
+    ),
+)
+
+# Update operations (with etag/version control)
+@mcp.tool(
+    title="Update Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # ETag changes = different inputs
+        openWorldHint=True,
+    ),
+)
+
+# Delete operations
+@mcp.tool(
+    title="Delete Resource",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Permanently deletes data
+        idempotentHint=True,    # Same end state if called repeatedly
+        openWorldHint=True,
+    ),
+)
+
+# HTTP PUT without version control (special case)
+@mcp.tool(
+    title="Write File",
+    annotations=ToolAnnotations(
+        idempotentHint=True,  # Same content = same end state
+        openWorldHint=True,
+    ),
+)
+```
+
+**Key Principles**:
+- **Idempotency**: Same inputs → same result. ETags change after updates, making them non-idempotent
+- **Destructive**: Operations that permanently delete/overwrite data
+- **Open World**: All Nextcloud tools access external service (openWorldHint=True)
+- **Titles**: Use human-readable names, not snake_case function names
+
+**See**: `docs/ADR-017-mcp-tool-annotations.md` for detailed rationale and examples
+
 ### Project Structure
 - `nextcloud_mcp_server/client/` - HTTP clients for Nextcloud APIs
 - `nextcloud_mcp_server/server/` - MCP tool/resource definitions
@@ -1,6 +1,6 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:b43ff04d5df04ad5cabb80890b7ef74e8410e3395b19af970dcd52d7a4bff921
+FROM docker.io/library/python:3.12-slim-trixie@sha256:590cad70271b6c1795c6a11fb5c110efca593adbd0d4883cd19c36df6a56467b

-COPY --from=ghcr.io/astral-sh/uv:0.9.16@sha256:ae9ff79d095a61faf534a882ad6378e8159d2ce322691153d68d2afac7422840 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.9.17@sha256:5cb6b54d2bc3fe2eb9a8483db958a0b9eebf9edff68adedb369df8e7b98711a2 /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -12,12 +12,12 @@
 # - Per-session app password authentication
 # - Multi-user support via Smithery session config

-FROM docker.io/library/python:3.12-slim-trixie@sha256:b43ff04d5df04ad5cabb80890b7ef74e8410e3395b19af970dcd52d7a4bff921
+FROM docker.io/library/python:3.12-slim-trixie@sha256:590cad70271b6c1795c6a11fb5c110efca593adbd0d4883cd19c36df6a56467b

 WORKDIR /app

 # Install uv for fast dependency management
-COPY --from=ghcr.io/astral-sh/uv:0.9.16@sha256:ae9ff79d095a61faf534a882ad6378e8159d2ce322691153d68d2afac7422840 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.9.17@sha256:5cb6b54d2bc3fe2eb9a8483db958a0b9eebf9edff68adedb369df8e7b98711a2 /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -1,11 +1,12 @@
+```markdown
 <p align="center">
  <img src="astrolabe.svg" alt="Nextcloud MCP Server" width="128" height="128">
 </p>

 # Nextcloud MCP Server

-[![Docker Image](https://img.shields.io/badge/docker-ghcr.io/cbcoutinho/nextcloud--mcp--server-blue)](https://github.com/cbcoutinho/nextcloud-mcp-server/pkgs/container/nextcloud-mcp-server)
 [![smithery badge](https://smithery.ai/badge/@cbcoutinho/nextcloud-mcp-server)](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server)
+[![Docker Image](https://img.shields.io/badge/docker-ghcr.io/cbcoutinho/nextcloud--mcp--server-blue)](https://github.com/cbcoutinho/nextcloud-mcp-server/pkgs/container/nextcloud-mcp-server)

 **A production-ready MCP server that connects AI assistants to your Nextcloud instance.**

@@ -223,3 +224,4 @@ This project is licensed under the AGPL-3.0 License. See [LICENSE](./LICENSE) fo
 - [Model Context Protocol](https://github.com/modelcontextprotocol)
 - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
 - [Nextcloud](https://nextcloud.com/)
+```
@@ -2,8 +2,8 @@ apiVersion: v2
 name: nextcloud-mcp-server
 description: A Helm chart for Nextcloud MCP Server - enables AI assistants to interact with Nextcloud
 type: application
-version: 0.49.0
-appVersion: "0.49.0"
+version: 0.50.0
+appVersion: "0.50.0"
 keywords:
  - nextcloud
  - mcp
@@ -21,7 +21,7 @@ services:
    restart: always

  app:
-    image: docker.io/library/nextcloud:32.0.2@sha256:8cb1dc8c26944115469dd22f4965d2ed35bab9cf8c48d2bb052c8e9f83821ded
+    image: docker.io/library/nextcloud:32.0.2@sha256:04cc19547e586ac75e08dd056c11330d4ce4c5c561c89405b326180a37c19afb
    restart: always
    ports:
      - 0.0.0.0:8080:80
@@ -51,7 +51,7 @@ services:
      retries: 30

  recipes:
-    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
+    image: docker.io/library/nginx:alpine@sha256:289decab414250121a93c3f1b8316b9c69906de3a4993757c424cb964169ad42
    restart: always
    volumes:
      - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
@@ -0,0 +1,506 @@
+# ADR-017: Add MCP Tool Annotations for Enhanced Client UX
+
+## Status
+
+Implemented
+
+## Context
+
+The MCP Python SDK supports tool annotations that provide behavioral hints and improved UX to MCP clients. Currently, our 101 tools across 10 modules lack these annotations, resulting in:
+
+- Snake_case function names displayed to users (e.g., "nc_notes_create_note" instead of "Create Note")
+- No behavioral hints for clients about read-only, destructive, or idempotent operations
+- Missing parameter descriptions for better auto-completion and inline help
+- Clients cannot optimize caching, warn before destructive operations, or retry safely
+
+### Available MCP Annotations
+
+The MCP SDK provides three types of annotations:
+
+#### 1. Tool Decorator Parameters
+```python
+@mcp.tool(
+    title="Human-Readable Name",
+    description="Tool description",  # Can also come from docstring
+    annotations=ToolAnnotations(...),
+    icons=[Icon(...)]  # Optional visual icons
+)
+```
+
+#### 2. ToolAnnotations Behavioral Hints
+```python
+from mcp.types import ToolAnnotations
+
+ToolAnnotations(
+    title="Alternative Title",  # Decorator title takes precedence
+    readOnlyHint=True,         # Tool doesn't modify data
+    destructiveHint=True,       # Tool may delete/overwrite data
+    idempotentHint=True,        # Repeated calls with same args are safe
+    openWorldHint=True          # Interacts with external entities
+)
+```
+
+#### 3. Parameter Descriptions
+```python
+from pydantic import Field
+
+async def tool(
+    param: str = Field(description="What this parameter does"),
+    ctx: Context
+):
+```
+
+### Idempotency Analysis
+
+**Important**: Idempotency means calling with **the same inputs** produces the same result.
+
+**NOT Idempotent** (different inputs each call):
+- **Updates with etag**: `update_note(id=1, title="X", etag="abc")` → etag changes to "def"
+  - Second call: `update_note(id=1, title="X", etag="abc")` → fails (etag mismatch)
+  - Different input (stale etag) → different result (error)
+- **Creates**: `create_note(title="X")` → creates note 1
+  - Second call → creates note 2 (different result)
+- **Append operations**: `append_content(id=1, text="X")` → adds X once
+  - Second call → adds X again (different result)
+
+**Idempotent**:
+- **Deletes**: `delete_note(id=1)` → note deleted
+  - Second call → 404 or success (same end state: note doesn't exist)
+  - Note: May return different status code, but end state is identical
+- **Full resource PUT without version control**: `write_file(path="/test.txt", content="Hello")` → file has "Hello"
+  - Second call → file still has "Hello" (same end state)
+  - Example: `nc_webdav_write_file` uses HTTP PUT without etags/version control
+- **Set operations**: `set_property(id=1, value="X")` → property = X
+  - Second call → property still = X (same result)
+  - Note: Nextcloud updates with etags use version control, so not idempotent
+
+**Read-Only** (always idempotent, never destructive):
+- All list, search, get operations
+
+## Decision
+
+Add annotations to all 101 tools in three phases:
+
+### Phase 1: Titles (Quick Win)
+Add human-readable titles to all tools:
+
+```python
+@mcp.tool(title="Create Note")
+async def nc_notes_create_note(...):
+```
+
+**Effort**: 2-3 hours
+**Impact**: Immediate UX improvement
+
+### Phase 2: ToolAnnotations (Behavioral Hints)
+Add annotations based on corrected categorization:
+
+```python
+# Read-only tools
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True  # Nextcloud is external to MCP server
+    )
+)
+
+# Delete tools (idempotent: same end state)
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,
+        idempotentHint=True,  # Deleting deleted item = same end state
+        openWorldHint=True
+    )
+)
+
+# Create tools (not idempotent: creates multiple items)
+@mcp.tool(
+    title="Create Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+
+# Update tools with etag (not idempotent: etag changes)
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Etag required = different inputs each time
+        openWorldHint=True
+    )
+)
+
+# Append operations (not idempotent: adds content each time)
+@mcp.tool(
+    title="Append to Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+```
+
+**Effort**: 4-6 hours
+**Impact**: Better client behavior (caching, warnings, retry logic)
+
+### Phase 3: Parameter Descriptions
+Add Field() descriptions to parameters:
+
+```python
+from pydantic import Field
+
+@mcp.tool(title="Create Note", annotations=ToolAnnotations(idempotentHint=False))
+async def nc_notes_create_note(
+    title: str = Field(description="The title of the note"),
+    content: str = Field(description="Markdown content of the note"),
+    category: str = Field(description="Category or folder name for organizing"),
+    ctx: Context
+) -> CreateNoteResponse:
+```
+
+**Effort**: 6-8 hours
+**Impact**: Better auto-completion and inline help
+
+## Tool Categorization
+
+### Read-Only Tools (~40 tools)
+**Pattern**: List, search, get operations
+**Annotations**: `readOnlyHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_search_notes` → "Search Notes"
+- `nc_webdav_list_directory` → "List Files and Directories"
+- `nc_calendar_list_calendars` → "List Calendars"
+- `nc_contacts_get_contact` → "Get Contact"
+- `nc_semantic_search` → "Semantic Search"
+- `check_logged_in` → "Check Server Login Status"
+
+### Create Tools (~20 tools)
+**Pattern**: Create new resources
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_create_note` → "Create Note"
+- `nc_calendar_create_event` → "Create Calendar Event"
+- `nc_contacts_create_contact` → "Create Contact"
+- `deck_create_card` → "Create Kanban Card"
+- `nc_tables_create_row` → "Create Table Row"
+
+### Update Tools (~25 tools)
+**Pattern**: Modify existing resources with etag
+**Annotations**: `idempotentHint=False` (etag changes), `openWorldHint=True`
+
+Examples:
+- `nc_notes_update_note` → "Update Note"
+- `nc_calendar_update_event` → "Update Calendar Event"
+- `nc_contacts_update_contact` → "Update Contact"
+- `deck_update_card` → "Update Kanban Card"
+
+**Rationale**: Updates require etag, which changes after each update. Same parameters on second call will fail due to stale etag = NOT idempotent.
+
+### Append/Accumulate Tools (~5 tools)
+**Pattern**: Add content without replacing
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_append_content` → "Append to Note"
+
+**Rationale**: Each call adds content, changing the result = NOT idempotent.
+
+### Delete Tools (~10 tools)
+**Pattern**: Remove resources
+**Annotations**: `destructiveHint=True`, `idempotentHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_delete_note` → "Delete Note"
+- `nc_webdav_delete_resource` → "Delete File or Directory"
+- `nc_calendar_delete_event` → "Delete Calendar Event"
+- `nc_contacts_delete_contact` → "Delete Contact"
+
+**Rationale**: Deleting already-deleted item results in same end state (item doesn't exist) = idempotent. Status code may differ, but outcome is identical.
+
+### Special Cases
+
+#### OAuth Provisioning Tools
+```python
+# Not read-only but requires user interaction
+@mcp.tool(
+    title="Grant Server Access to Nextcloud",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        idempotentHint=False,  # Creates new OAuth session each time
+        openWorldHint=True
+    )
+)
+async def provision_nextcloud_access(ctx: Context):
+```
+
+#### Semantic Search (Closed World)
+```python
+@mcp.tool(
+    title="Semantic Search",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=False  # Searches only indexed Nextcloud data
+    )
+)
+async def nc_semantic_search(query: str, ctx: Context):
+```
+
+**Rationale**: Semantic search only queries pre-indexed Nextcloud content, not the "open world" like web search would.
+
+## Tool Priority Matrix
+
+### Critical Priority (~2 tools)
+OAuth tools required for server functionality:
+- `provision_nextcloud_access` → "Grant Server Access to Nextcloud"
+- `check_logged_in` → "Check Server Login Status"
+
+### High Priority (~50 tools)
+Most commonly used modules:
+- **Notes** (14 tools): Create, read, update, delete notes
+- **WebDAV** (13 tools): File operations
+- **Calendar** (15 tools): Events and todos
+- **Semantic Search** (6 tools): AI-powered search
+- **Contacts** (9 tools): Address book operations
+
+### Medium Priority (~35 tools)
+Secondary functionality:
+- **Deck** (9 tools): Kanban boards
+- **Tables** (7 tools): Structured data
+- **Sharing** (5 tools): File sharing
+
+### Low Priority (~14 tools)
+Less frequently used:
+- **Cookbook** (8 tools): Recipe management
+- **News** (6 tools): RSS feeds
+
+## Implementation Plan
+
+### Week 1: Phase 1 - Titles
+- Add human-readable titles to all 101 tools
+- Update tool name mapping in documentation
+- Manual test in MCP inspector
+
+### Week 2: Phase 2 - ToolAnnotations (High Priority)
+- Add annotations to Critical and High priority tools (~52 tools)
+- Focus on Notes, WebDAV, Calendar, Semantic, OAuth
+- Add unit tests validating annotation presence
+
+### Week 3: Phase 2 - ToolAnnotations (Medium/Low Priority)
+- Complete remaining tools (~49 tools)
+- Deck, Tables, Contacts, Cookbook, News
+- Update tool listings in README
+
+### Week 4: Phase 3 - Parameter Descriptions
+- Add Field() descriptions to Critical/High priority tools
+- Start with OAuth, Notes, WebDAV modules
+- Incremental completion over time
+
+## Benefits
+
+### For Users
+- **Clearer UI**: "Create Note" vs "nc_notes_create_note"
+- **Safety**: Warnings before destructive operations
+- **Better help**: Parameter descriptions in auto-completion
+- **Confidence**: Know which operations are safe to retry
+
+### For MCP Clients
+- **Caching**: Cache results from read-only tools
+- **Safety prompts**: Warn before destructiveHint=true
+- **Retry logic**: Safely retry idempotent operations
+- **UI organization**: Group by behavior (reads vs writes vs deletes)
+- **Performance**: Optimize based on hints
+
+### For Developers
+- **Self-documenting**: Behavior is explicit
+- **Consistency**: Standard patterns across codebase
+- **Testing**: Validate annotations match implementation
+- **Maintenance**: Clear expectations for new tools
+
+## Consequences
+
+### Positive
+- Immediate UX improvement with minimal effort
+- Clients can make smarter decisions
+- Self-documenting code
+- Follows MCP best practices
+
+### Negative
+- Initial effort to add annotations (12-15 hours total)
+- Must maintain annotations when adding new tools
+- Risk of incorrect annotations misleading clients
+
+### Neutral
+- Annotations are hints, not guarantees
+- Clients may ignore annotations
+- Backward compatible (additive change)
+
+### Mitigations
+- **Incorrect annotations**: Add tests validating behavior matches hints
+- **Maintenance burden**: Add to code review checklist and tool template
+- **Documentation**: Update CLAUDE.md with annotation guidelines
+
+## Examples
+
+### Complete Annotated Tool (Delete)
+
+```python
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Deletes data permanently
+        idempotentHint=True,    # Same end state (note doesn't exist)
+        openWorldHint=True      # Nextcloud is external
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_delete_note(
+    note_id: int = Field(description="The ID of the note to delete permanently"),
+    ctx: Context
+) -> DeleteNoteResponse:
+    """Delete a note permanently (requires notes:write scope)"""
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Update)
+
+```python
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,   # NOT idempotent: etag changes each update
+        openWorldHint=True
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_update_note(
+    note_id: int = Field(description="The ID of the note to update"),
+    title: str | None = Field(
+        default=None,
+        description="New title (omit to keep current)"
+    ),
+    content: str | None = Field(
+        default=None,
+        description="New markdown content (omit to keep current)"
+    ),
+    category: str | None = Field(
+        default=None,
+        description="New category/folder (omit to keep current)"
+    ),
+    etag: str = Field(
+        description="ETag from get_note (prevents concurrent modification)"
+    ),
+    ctx: Context
+) -> UpdateNoteResponse:
+    """Update an existing note's title, content, or category.
+
+    The etag parameter is required to prevent overwriting concurrent changes.
+    Get the current ETag by first calling nc_notes_get_note.
+    If the note has been modified since you retrieved it, the update will fail.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Read-Only)
+
+```python
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,    # Doesn't modify data
+        openWorldHint=True    # Queries Nextcloud
+    )
+)
+@require_scopes("notes:read")
+@instrument_tool
+async def nc_notes_search_notes(
+    query: str = Field(description="Search term to match in note titles or content"),
+    ctx: Context
+) -> SearchNotesResponse:
+    """Search notes by title or content, returning id, title, and category.
+
+    This is a read-only operation that searches across all user notes.
+    Use nc_notes_get_note to retrieve the full content of matching notes.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+## Testing Strategy
+
+### Unit Tests
+Add tests validating annotation presence and correctness:
+
+```python
+def test_notes_tools_have_annotations():
+    """Verify all notes tools have appropriate annotations."""
+    tools = get_registered_tools(mcp)
+
+    # Check create tool
+    create_tool = tools["nc_notes_create_note"]
+    assert create_tool.title == "Create Note"
+    assert create_tool.annotations.idempotentHint is False
+
+    # Check delete tool
+    delete_tool = tools["nc_notes_delete_note"]
+    assert delete_tool.title == "Delete Note"
+    assert delete_tool.annotations.destructiveHint is True
+    assert delete_tool.annotations.idempotentHint is True
+
+    # Check read-only tool
+    search_tool = tools["nc_notes_search_notes"]
+    assert search_tool.title == "Search Notes"
+    assert search_tool.annotations.readOnlyHint is True
+```
+
+### Integration Tests
+- Verify existing tests pass with annotations
+- Manual testing in MCP inspector/client
+
+### Documentation Updates
+- Update README tool listings with new titles
+- Add annotation guidelines to CLAUDE.md
+- Include examples in developer documentation
+
+## Resolved Questions
+
+1. **WebDAV write_file idempotency** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `idempotentHint=True`
+   - **Rationale**: Uses HTTP PUT without version control. Writing same content to same path repeatedly produces identical end state, which is the definition of idempotency in HTTP semantics.
+
+2. **Semantic search openWorldHint** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `openWorldHint=True`
+   - **Rationale**: For consistency with other Nextcloud tools. While the data being searched is "indexed/internal", Nextcloud itself is external to the MCP server. The fact that data is indexed is an implementation detail, not a fundamental difference from other Nextcloud queries.
+
+3. **Read-only with side effects**: Should tools that log analytics still be readOnlyHint=true?
+   - **Decision**: Yes. Logging/analytics are non-visible side effects that don't change user-observable state. Read-only refers to data modifications that affect the user's content.
+
+## Future Considerations
+
+1. **Icons**: Visual icons for tools (requires design work, deferred to future ADR)
+2. **Parameter descriptions**: Add Pydantic `Field(description=...)` for better auto-completion (Phase 3, future work)
+
+## References
+
+- MCP Python SDK: `/home/chris/Software/python-sdk/`
+- ToolAnnotations spec: `src/mcp/types.py:1247`
+- FastMCP decorator: `src/mcp/server/fastmcp/server.py:444`
+- Examples: `examples/fastmcp/parameter_descriptions.py`, `examples/fastmcp/icons_demo.py`
+
+## Decision Timeline
+
+- **Proposed**: 2025-12-11
+- **Reviewed**: 2025-12-11 (Self-review during implementation)
+- **Accepted**: 2025-12-11
+- **Implemented**: 2025-12-11 (Phase 1 & 2 complete)
@@ -3,6 +3,7 @@ import logging
 from typing import Optional

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -19,7 +20,10 @@ logger = logging.getLogger(__name__)

 def configure_calendar_tools(mcp: FastMCP):
    # Calendar tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Calendars",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("calendar:read")
    @instrument_tool
    async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
@@ -30,7 +34,10 @@ def configure_calendar_tools(mcp: FastMCP):
        calendars = [Calendar(**cal_data) for cal_data in calendars_data]
        return ListCalendarsResponse(calendars=calendars, total_count=len(calendars))

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Calendar Event",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_create_event(
@@ -107,7 +114,10 @@ def configure_calendar_tools(mcp: FastMCP):

        return await client.calendar.create_event(calendar_name, event_data)

-    @mcp.tool()
+    @mcp.tool(
+        title="List Calendar Events",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("calendar:read")
    @instrument_tool
    async def nc_calendar_list_events(
@@ -210,7 +220,10 @@ def configure_calendar_tools(mcp: FastMCP):

            return events

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Calendar Event",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("calendar:read")
    @instrument_tool
    async def nc_calendar_get_event(
@@ -223,7 +236,10 @@ def configure_calendar_tools(mcp: FastMCP):
        event_data, etag = await client.calendar.get_event(calendar_name, event_uid)
        return event_data

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Calendar Event",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_update_event(
@@ -297,7 +313,12 @@ def configure_calendar_tools(mcp: FastMCP):
            calendar_name, event_uid, event_data, etag
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Calendar Event",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_delete_event(
@@ -309,7 +330,10 @@ def configure_calendar_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.calendar.delete_event(calendar_name, event_uid)

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Meeting",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_create_meeting(
@@ -376,7 +400,10 @@ def configure_calendar_tools(mcp: FastMCP):

        return await client.calendar.create_event(calendar_name, event_data)

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Upcoming Events",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("calendar:read")
    @instrument_tool
    async def nc_calendar_get_upcoming_events(
@@ -427,7 +454,10 @@ def configure_calendar_tools(mcp: FastMCP):
            all_events.sort(key=lambda x: x.get("start_datetime", ""))
            return all_events[:limit]

-    @mcp.tool()
+    @mcp.tool(
+        title="Find Availability",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("calendar:read")
    @instrument_tool
    async def nc_calendar_find_availability(
@@ -508,7 +538,10 @@ def configure_calendar_tools(mcp: FastMCP):
            constraints=constraints,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Bulk Calendar Operations",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_bulk_operations(
@@ -758,7 +791,10 @@ def configure_calendar_tools(mcp: FastMCP):
                "results": results,
            }

-    @mcp.tool()
+    @mcp.tool(
+        title="Manage Calendar",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("calendar:write")
    @instrument_tool
    async def nc_calendar_manage_calendar(
@@ -828,7 +864,10 @@ def configure_calendar_tools(mcp: FastMCP):

    # ============= Todo/Task Tools =============

-    @mcp.tool()
+    @mcp.tool(
+        title="List Todo Tasks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("todo:read", "calendar:read")
    @instrument_tool
    async def nc_calendar_list_todos(
@@ -874,7 +913,10 @@ def configure_calendar_tools(mcp: FastMCP):
            todos=todos, calendar_name=calendar_name, total_count=len(todos)
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Todo Task",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("todo:write", "calendar:read")
    @instrument_tool
    async def nc_calendar_create_todo(
@@ -918,7 +960,10 @@ def configure_calendar_tools(mcp: FastMCP):

        return await client.calendar.create_todo(calendar_name, todo_data)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Todo Task",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("todo:write", "calendar:read")
    @instrument_tool
    async def nc_calendar_update_todo(
@@ -979,7 +1024,12 @@ def configure_calendar_tools(mcp: FastMCP):

        return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Todo Task",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("todo:write", "calendar:read")
    @instrument_tool
    async def nc_calendar_delete_todo(
@@ -1000,7 +1050,10 @@ def configure_calendar_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.calendar.delete_todo(calendar_name, todo_uid)

-    @mcp.tool()
+    @mcp.tool(
+        title="Search Todo Tasks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("todo:read", "calendar:read")
    @instrument_tool
    async def nc_calendar_search_todos(
@@ -1,6 +1,7 @@
 import logging

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -11,7 +12,10 @@ logger = logging.getLogger(__name__)

 def configure_contacts_tools(mcp: FastMCP):
    # Contacts tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Address Books",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("contacts:read")
    @instrument_tool
    async def nc_contacts_list_addressbooks(ctx: Context):
@@ -19,7 +23,10 @@ def configure_contacts_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.contacts.list_addressbooks()

-    @mcp.tool()
+    @mcp.tool(
+        title="List Contacts",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("contacts:read")
    @instrument_tool
    async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
@@ -27,7 +34,10 @@ def configure_contacts_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.contacts.list_contacts(addressbook=addressbook)

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Address Book",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_create_addressbook(
@@ -44,7 +54,12 @@ def configure_contacts_tools(mcp: FastMCP):
            name=name, display_name=display_name
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Address Book",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
@@ -52,7 +67,10 @@ def configure_contacts_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.contacts.delete_addressbook(name=name)

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Contact",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_create_contact(
@@ -70,7 +88,12 @@ def configure_contacts_tools(mcp: FastMCP):
            addressbook=addressbook, uid=uid, contact_data=contact_data
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Contact",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
@@ -78,7 +101,10 @@ def configure_contacts_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Contact",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_update_contact(
@@ -3,7 +3,7 @@ import logging
 from httpx import HTTPStatusError, RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
-from mcp.types import ErrorData
+from mcp.types import ErrorData, ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -71,7 +71,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Import Recipe from URL",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
@@ -129,7 +132,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipes",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
@@ -155,7 +161,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipe",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
@@ -181,7 +190,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Recipe",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_create_recipe(
@@ -261,7 +273,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Recipe",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_update_recipe(
@@ -351,7 +366,12 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Recipe",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_delete_recipe(
@@ -387,7 +407,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Search Recipes",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_search_recipes(
@@ -424,7 +447,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipe Categories",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
@@ -452,7 +478,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipes in Category",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_get_recipes_in_category(
@@ -489,7 +518,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipe Keywords",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
@@ -515,7 +547,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipes with Keywords",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("cookbook:read")
    @instrument_tool
    async def nc_cookbook_get_recipes_with_keywords(
@@ -550,7 +585,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Set Cookbook Configuration",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_set_config(
@@ -594,7 +632,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Reindex Recipes",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("cookbook:write")
    @instrument_tool
    async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:
@@ -2,6 +2,7 @@ import logging
 from typing import Optional

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -117,7 +118,10 @@ def configure_deck_tools(mcp: FastMCP):

    # Read Tools (converted from resources)

-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Boards",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
@@ -126,7 +130,10 @@ def configure_deck_tools(mcp: FastMCP):
        boards = await client.deck.get_boards()
        return boards

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Board",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
@@ -135,7 +142,10 @@ def configure_deck_tools(mcp: FastMCP):
        board = await client.deck.get_board(board_id)
        return board

-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Stacks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
@@ -144,7 +154,10 @@ def configure_deck_tools(mcp: FastMCP):
        stacks = await client.deck.get_stacks(board_id)
        return stacks

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Stack",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
@@ -153,7 +166,10 @@ def configure_deck_tools(mcp: FastMCP):
        stack = await client.deck.get_stack(board_id, stack_id)
        return stack

-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Cards",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_cards(
@@ -166,7 +182,10 @@ def configure_deck_tools(mcp: FastMCP):
            return stack.cards
        return []

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Card",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_card(
@@ -177,7 +196,10 @@ def configure_deck_tools(mcp: FastMCP):
        card = await client.deck.get_card(board_id, stack_id, card_id)
        return card

-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Labels",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
@@ -186,7 +208,10 @@ def configure_deck_tools(mcp: FastMCP):
        board = await client.deck.get_board(board_id)
        return board.labels

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Label",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("deck:read")
    @instrument_tool
    async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
@@ -197,7 +222,10 @@ def configure_deck_tools(mcp: FastMCP):

    # Create/Update/Delete Tools

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Board",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_create_board(
@@ -215,7 +243,10 @@ def configure_deck_tools(mcp: FastMCP):

    # Stack Tools

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Stack",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_create_stack(
@@ -232,7 +263,10 @@ def configure_deck_tools(mcp: FastMCP):
        stack = await client.deck.create_stack(board_id, title, order)
        return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Stack",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_update_stack(
@@ -259,7 +293,12 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Stack",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_delete_stack(
@@ -281,7 +320,10 @@ def configure_deck_tools(mcp: FastMCP):
        )

    # Card Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_create_card(
@@ -316,7 +358,10 @@ def configure_deck_tools(mcp: FastMCP):
            stackId=card.stackId,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_update_card(
@@ -370,7 +415,12 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Card",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_delete_card(
@@ -393,7 +443,10 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Archive Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_archive_card(
@@ -416,7 +469,10 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Unarchive Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_unarchive_card(
@@ -439,7 +495,10 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Reorder/Move Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_reorder_card(
@@ -472,7 +531,10 @@ def configure_deck_tools(mcp: FastMCP):
        )

    # Label Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Label",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_create_label(
@@ -489,7 +551,10 @@ def configure_deck_tools(mcp: FastMCP):
        label = await client.deck.create_label(board_id, title, color)
        return CreateLabelResponse(id=label.id, title=label.title, color=label.color)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Label",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_update_label(
@@ -516,7 +581,12 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Label",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_delete_label(
@@ -538,7 +608,10 @@ def configure_deck_tools(mcp: FastMCP):
        )

    # Card-Label Assignment Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Assign Label to Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_assign_label_to_card(
@@ -562,7 +635,10 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Remove Label from Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_remove_label_from_card(
@@ -587,7 +663,10 @@ def configure_deck_tools(mcp: FastMCP):
        )

    # Card-User Assignment Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Assign User to Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_assign_user_to_card(
@@ -611,7 +690,10 @@ def configure_deck_tools(mcp: FastMCP):
            board_id=board_id,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Unassign User from Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("deck:write")
    @instrument_tool
    async def deck_unassign_user_from_card(
@@ -5,7 +5,7 @@ import logging
 from httpx import HTTPStatusError, RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
-from mcp.types import ErrorData
+from mcp.types import ErrorData, ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.client.news import NewsItemType
@@ -30,7 +30,10 @@ logger = logging.getLogger(__name__)
 def configure_news_tools(mcp: FastMCP):
    """Configure News app MCP tools."""

-    @mcp.tool()
+    @mcp.tool(
+        title="List News Folders",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_list_folders(ctx: Context) -> ListFoldersResponse:
@@ -52,7 +55,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="List News Feeds",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_list_feeds(ctx: Context) -> ListFeedsResponse:
@@ -82,7 +88,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="List News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_list_items(
@@ -153,7 +162,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get News Item",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_get_item(item_id: int, ctx: Context) -> GetItemResponse:
@@ -188,7 +200,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Starred News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_get_starred_items(
@@ -238,7 +253,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Unread News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_get_unread_items(
@@ -288,7 +306,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get News Feed Health",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_get_feed_health(feed_id: int, ctx: Context) -> FeedHealthResponse:
@@ -332,7 +353,10 @@ def configure_news_tools(mcp: FastMCP):
                )
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get News App Status",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("news:read")
    @instrument_tool
    async def nc_news_get_status(ctx: Context) -> GetStatusResponse:
@@ -3,7 +3,7 @@ import logging
 from httpx import HTTPStatusError, RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
-from mcp.types import ErrorData
+from mcp.types import ErrorData, ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -85,7 +85,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Multiple calls create multiple notes
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:write")
    @instrument_tool
    async def nc_notes_create_note(
@@ -132,7 +138,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Requires etag which changes = not idempotent
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:write")
    @instrument_tool
    async def nc_notes_update_note(
@@ -198,7 +210,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Append to Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Each call adds content = not idempotent
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:write")
    @instrument_tool
    async def nc_notes_append_content(
@@ -249,7 +267,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Search Notes",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:read")
    @instrument_tool
    async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
@@ -296,7 +320,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Note",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Read operation only
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:read")
    @instrument_tool
    async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
@@ -326,7 +356,13 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Note Attachment",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Read operation only
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:read")
    @instrument_tool
    async def nc_notes_get_attachment(
@@ -373,7 +409,14 @@ def configure_notes_tools(mcp: FastMCP):
                    )
                )

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Note",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Permanently deletes data
+            idempotentHint=True,  # Deleting deleted note = same end state
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("notes:write")
    @instrument_tool
    async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
@@ -15,6 +15,7 @@ import httpx
 from mcp.server.auth.middleware.auth_context import get_access_token
 from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
+from mcp.types import ToolAnnotations
 from pydantic import BaseModel, Field

 from nextcloud_mcp_server.auth import require_scopes
@@ -684,11 +685,16 @@ def register_oauth_tools(mcp):

    @mcp.tool(
        name="provision_nextcloud_access",
+        title="Grant Server Access to Nextcloud",
        description=(
            "Provision offline access to Nextcloud resources. "
            "This is required before using Nextcloud tools. "
            "You'll need to complete an OAuth authorization in your browser."
        ),
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Creates new OAuth session each time
+            openWorldHint=True,
+        ),
    )
    @require_scopes("openid")
    async def tool_provision_access(
@@ -699,7 +705,13 @@ def register_oauth_tools(mcp):

    @mcp.tool(
        name="revoke_nextcloud_access",
+        title="Revoke Server Access to Nextcloud",
        description="Revoke offline access to Nextcloud resources.",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Removes stored access tokens
+            idempotentHint=True,  # Revoking revoked access = same end state
+            openWorldHint=True,
+        ),
    )
    @require_scopes("openid")
    async def tool_revoke_access(
@@ -709,7 +721,12 @@ def register_oauth_tools(mcp):

    @mcp.tool(
        name="check_provisioning_status",
+        title="Check Provisioning Status",
        description="Check whether Nextcloud access is provisioned.",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Only checks status, doesn't modify
+            openWorldHint=True,
+        ),
    )
    @require_scopes("openid")
    async def tool_check_status(
@@ -719,10 +736,15 @@ def register_oauth_tools(mcp):

    @mcp.tool(
        name="check_logged_in",
+        title="Check Server Login Status",
        description=(
            "Check if you are logged in to Nextcloud. "
            "If not logged in, this tool will prompt you to complete the login flow."
        ),
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Checking status doesn't modify state
+            openWorldHint=True,
+        ),
    )
    @require_scopes("openid")
    async def tool_check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:
@@ -12,6 +12,7 @@ from mcp.types import (
    ModelPreferences,
    SamplingMessage,
    TextContent,
+    ToolAnnotations,
 )

 from nextcloud_mcp_server.auth import require_scopes
@@ -34,7 +35,13 @@ logger = logging.getLogger(__name__)
 def configure_semantic_tools(mcp: FastMCP):
    """Configure semantic search tools for MCP server."""

-    @mcp.tool()
+    @mcp.tool(
+        title="Semantic Search",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=True,  # Queries external Nextcloud service
+        ),
+    )
    @require_scopes("semantic:read")
    @instrument_tool
    async def nc_semantic_search(
@@ -285,7 +292,13 @@ def configure_semantic_tools(mcp: FastMCP):
            logger.error(f"Search error: {e}", exc_info=True)
            raise McpError(ErrorData(code=-1, message=f"Search failed: {str(e)}"))

-    @mcp.tool()
+    @mcp.tool(
+        title="Search with AI-Generated Answer",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=False,  # Searches only indexed Nextcloud data
+        ),
+    )
    @require_scopes("semantic:read")
    @instrument_tool
    async def nc_semantic_search_answer(
@@ -623,7 +636,13 @@ def configure_semantic_tools(mcp: FastMCP):
                success=True,
            )

-    @mcp.tool()
+    @mcp.tool(
+        title="Check Indexing Status",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Only checks status
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("semantic:read")
    @instrument_tool
    async def nc_get_vector_sync_status(ctx: Context) -> VectorSyncStatusResponse:
@@ -3,6 +3,7 @@
 import json

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -16,7 +17,10 @@ def configure_sharing_tools(mcp: FastMCP):
        mcp: FastMCP server instance
    """

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Share",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("sharing:write")
    @instrument_tool
    async def nc_share_create(
@@ -56,7 +60,12 @@ def configure_sharing_tools(mcp: FastMCP):
        )
        return json.dumps(share_data, indent=2)

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Share",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("sharing:write")
    @instrument_tool
    async def nc_share_delete(share_id: int, ctx: Context) -> str:
@@ -76,7 +85,10 @@ def configure_sharing_tools(mcp: FastMCP):
            {"success": True, "message": f"Share {share_id} deleted"}, indent=2
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Share Details",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("sharing:write")
    @instrument_tool
    async def nc_share_get(share_id: int, ctx: Context) -> str:
@@ -95,7 +107,10 @@ def configure_sharing_tools(mcp: FastMCP):
        share_data = await client.sharing.get_share(share_id)
        return json.dumps(share_data, indent=2)

-    @mcp.tool()
+    @mcp.tool(
+        title="List Shares",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("sharing:write")
    @instrument_tool
    async def nc_share_list(
@@ -117,7 +132,10 @@ def configure_sharing_tools(mcp: FastMCP):
        )
        return json.dumps(shares, indent=2)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Share",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("sharing:write")
    @instrument_tool
    async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:
@@ -1,6 +1,7 @@
 import logging

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -11,7 +12,10 @@ logger = logging.getLogger(__name__)

 def configure_tables_tools(mcp: FastMCP):
    # Tables tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Tables",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("tables:read")
    @instrument_tool
    async def nc_tables_list_tables(ctx: Context):
@@ -19,7 +23,10 @@ def configure_tables_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.tables.list_tables()

-    @mcp.tool()
+    @mcp.tool(
+        title="Get Table Schema",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("tables:read")
    @instrument_tool
    async def nc_tables_get_schema(table_id: int, ctx: Context):
@@ -27,7 +34,10 @@ def configure_tables_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.tables.get_table_schema(table_id)

-    @mcp.tool()
+    @mcp.tool(
+        title="Read Table Rows",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
    @require_scopes("tables:read")
    @instrument_tool
    async def nc_tables_read_table(
@@ -40,7 +50,10 @@ def configure_tables_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.tables.get_table_rows(table_id, limit, offset)

-    @mcp.tool()
+    @mcp.tool(
+        title="Insert Table Row",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("tables:write")
    @instrument_tool
    async def nc_tables_insert_row(table_id: int, data: dict, ctx: Context):
@@ -51,7 +64,10 @@ def configure_tables_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.tables.create_row(table_id, data)

-    @mcp.tool()
+    @mcp.tool(
+        title="Update Table Row",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
    @require_scopes("tables:write")
    @instrument_tool
    async def nc_tables_update_row(row_id: int, data: dict, ctx: Context):
@@ -62,7 +78,12 @@ def configure_tables_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.tables.update_row(row_id, data)

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Table Row",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
    @require_scopes("tables:write")
    @instrument_tool
    async def nc_tables_delete_row(row_id: int, ctx: Context):
@@ -1,6 +1,7 @@
 import logging

 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -16,7 +17,13 @@ logger = logging.getLogger(__name__)

 def configure_webdav_tools(mcp: FastMCP):
    # WebDAV file system tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Files and Directories",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_list_directory(
@@ -50,7 +57,13 @@ def configure_webdav_tools(mcp: FastMCP):
            total_size=total_size,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Read File",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_read_file(path: str, ctx: Context):
@@ -117,7 +130,13 @@ def configure_webdav_tools(mcp: FastMCP):
            "encoding": "base64",
        }

-    @mcp.tool()
+    @mcp.tool(
+        title="Write File",
+        annotations=ToolAnnotations(
+            idempotentHint=True,  # HTTP PUT without version control is idempotent
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:write")
    @instrument_tool
    async def nc_webdav_write_file(
@@ -146,7 +165,13 @@ def configure_webdav_tools(mcp: FastMCP):

        return await client.webdav.write_file(path, content_bytes, content_type)

-    @mcp.tool()
+    @mcp.tool(
+        title="Create Directory",
+        annotations=ToolAnnotations(
+            idempotentHint=True,  # Creating existing dir returns 405 = same end state
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:write")
    @instrument_tool
    async def nc_webdav_create_directory(path: str, ctx: Context):
@@ -161,7 +186,14 @@ def configure_webdav_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.webdav.create_directory(path)

-    @mcp.tool()
+    @mcp.tool(
+        title="Delete File or Directory",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Permanently deletes data
+            idempotentHint=True,  # Deleting deleted resource = same end state
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:write")
    @instrument_tool
    async def nc_webdav_delete_resource(path: str, ctx: Context):
@@ -176,7 +208,13 @@ def configure_webdav_tools(mcp: FastMCP):
        client = await get_client(ctx)
        return await client.webdav.delete_resource(path)

-    @mcp.tool()
+    @mcp.tool(
+        title="Move or Rename File",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Moving changes source and dest
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:write")
    @instrument_tool
    async def nc_webdav_move_resource(
@@ -197,7 +235,13 @@ def configure_webdav_tools(mcp: FastMCP):
            source_path, destination_path, overwrite
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Copy File or Directory",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Creates new resource each time
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:write")
    @instrument_tool
    async def nc_webdav_copy_resource(
@@ -218,7 +262,13 @@ def configure_webdav_tools(mcp: FastMCP):
            source_path, destination_path, overwrite
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Search Files",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_search_files(
@@ -335,7 +385,13 @@ def configure_webdav_tools(mcp: FastMCP):
            filters_applied=filters if filters else None,
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Find Files by Name",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_find_by_name(
@@ -363,7 +419,13 @@ def configure_webdav_tools(mcp: FastMCP):
            filters_applied={"name_pattern": pattern},
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="Find Files by Type",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_find_by_type(
@@ -391,7 +453,13 @@ def configure_webdav_tools(mcp: FastMCP):
            filters_applied={"mime_type": mime_type},
        )

-    @mcp.tool()
+    @mcp.tool(
+        title="List Favorite Files",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
    @require_scopes("files:read")
    @instrument_tool
    async def nc_webdav_list_favorites(
@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.49.0"
+version = "0.50.0"
 description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
 authors = [
    {name = "Chris Coutinho", email = "chris@coutinho.io"}
@@ -10,7 +10,7 @@ license = {text = "AGPL-3.0-only"}
 requires-python = ">=3.11"
 keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
 dependencies = [
-    "mcp[cli] (>=1.23,<1.24)",
+    "mcp[cli] (>=1.22,<1.23)",
    "httpx (>=0.28.1,<0.29.0)",
    "pillow (>=10.3.0,<12.0.0)", # Compatible with fastembed
    "icalendar (>=6.0.0,<7.0.0)",
@@ -0,0 +1,193 @@
+"""Tests for MCP tool annotations (ADR-017)."""
+
+import pytest
+from mcp import ClientSession
+
+pytestmark = pytest.mark.integration
+
+
+async def test_all_tools_have_titles(nc_mcp_client: ClientSession):
+    """Verify all tools have human-readable titles (Phase 1 of ADR-017)."""
+    tools = await nc_mcp_client.list_tools()
+
+    # Every tool should have a title (not None)
+    for tool in tools.tools:
+        assert tool.title is not None, f"Tool {tool.name} is missing a title"
+        # Title should not be empty
+        assert tool.title.strip() != "", f"Tool {tool.name} has an empty title"
+        # Title should be human-readable (not snake_case function name)
+        assert tool.title != tool.name, (
+            f"Tool {tool.name} title is same as function name"
+        )
+
+
+async def test_all_tools_have_annotations(nc_mcp_client: ClientSession):
+    """Verify all tools have ToolAnnotations (Phase 2 of ADR-017)."""
+    tools = await nc_mcp_client.list_tools()
+
+    for tool in tools.tools:
+        # Every tool should have annotations
+        assert tool.annotations is not None, f"Tool {tool.name} is missing annotations"
+
+
+async def test_read_only_tools_have_correct_annotations(nc_mcp_client: ClientSession):
+    """Verify read-only tools are marked correctly."""
+    tools = await nc_mcp_client.list_tools()
+
+    # Known read-only tools (list, search, get operations)
+    read_only_prefixes = ["list", "search", "get"]
+    read_only_patterns = ["_get_", "_list_", "_search_"]
+
+    for tool in tools.tools:
+        # Check if tool name suggests it's read-only
+        is_likely_readonly = tool.name.startswith(tuple(read_only_prefixes)) or any(
+            pattern in tool.name for pattern in read_only_patterns
+        )
+
+        if is_likely_readonly:
+            assert tool.annotations is not None, f"Tool {tool.name} missing annotations"
+            assert tool.annotations.readOnlyHint is True, (
+                f"Read-only tool {tool.name} should have readOnlyHint=True"
+            )
+            assert tool.annotations.destructiveHint is not True, (
+                f"Read-only tool {tool.name} should not have destructiveHint=True"
+            )
+
+
+async def test_destructive_tools_have_correct_annotations(nc_mcp_client: ClientSession):
+    """Verify destructive operations are marked correctly."""
+    tools = await nc_mcp_client.list_tools()
+
+    # Known destructive operations
+    destructive_keywords = ["delete", "remove", "revoke"]
+
+    for tool in tools.tools:
+        has_destructive_keyword = any(
+            keyword in tool.name.lower() for keyword in destructive_keywords
+        )
+
+        if has_destructive_keyword:
+            assert tool.annotations is not None, f"Tool {tool.name} missing annotations"
+            assert tool.annotations.destructiveHint is True, (
+                f"Destructive tool {tool.name} should have destructiveHint=True"
+            )
+
+
+async def test_delete_operations_are_idempotent(nc_mcp_client: ClientSession):
+    """Verify delete operations are marked as idempotent (ADR-017 decision)."""
+    tools = await nc_mcp_client.list_tools()
+
+    for tool in tools.tools:
+        if "delete" in tool.name.lower():
+            assert tool.annotations is not None, f"Tool {tool.name} missing annotations"
+            assert tool.annotations.idempotentHint is True, (
+                f"Delete tool {tool.name} should be idempotent (same end state)"
+            )
+
+
+async def test_create_operations_not_idempotent(nc_mcp_client: ClientSession):
+    """Verify create operations are marked as non-idempotent."""
+    tools = await nc_mcp_client.list_tools()
+
+    for tool in tools.tools:
+        if "create" in tool.name.lower() and "calendar_create_meeting" not in tool.name:
+            assert tool.annotations is not None, f"Tool {tool.name} missing annotations"
+            assert tool.annotations.idempotentHint is not True, (
+                f"Create tool {tool.name} should not be idempotent (creates new resources)"
+            )
+
+
+async def test_update_operations_not_idempotent(nc_mcp_client: ClientSession):
+    """Verify update operations are marked as non-idempotent (due to etag requirements)."""
+    tools = await nc_mcp_client.list_tools()
+
+    for tool in tools.tools:
+        if "update" in tool.name.lower():
+            assert tool.annotations is not None, f"Tool {tool.name} missing annotations"
+            # Most updates use etags which change each time, making them non-idempotent
+            # Exception: calendar_update_event might be different
+            assert tool.annotations.idempotentHint is not True, (
+                f"Update tool {tool.name} should not be idempotent (etag changes)"
+            )
+
+
+async def test_webdav_write_is_idempotent(nc_mcp_client: ClientSession):
+    """Verify nc_webdav_write_file is marked as idempotent (ADR-017 decision).
+
+    WebDAV write uses HTTP PUT without version control, making it idempotent.
+    Writing same content to same path repeatedly produces same end state.
+    """
+    tools = await nc_mcp_client.list_tools()
+
+    write_tool = next(
+        (tool for tool in tools.tools if tool.name == "nc_webdav_write_file"), None
+    )
+    assert write_tool is not None, "nc_webdav_write_file tool not found"
+    assert write_tool.annotations is not None, "write_file missing annotations"
+    assert write_tool.annotations.idempotentHint is True, (
+        "nc_webdav_write_file should be idempotent (HTTP PUT without version control)"
+    )
+
+
+async def test_semantic_search_open_world(nc_mcp_client: ClientSession):
+    """Verify semantic search has openWorldHint=True (ADR-017 decision).
+
+    Semantic search queries external Nextcloud service, consistent with other tools.
+    """
+    tools = await nc_mcp_client.list_tools()
+
+    semantic_tool = next(
+        (tool for tool in tools.tools if tool.name == "nc_semantic_search"), None
+    )
+    if semantic_tool:  # Only if semantic search is enabled
+        assert semantic_tool.annotations is not None, (
+            "semantic_search missing annotations"
+        )
+        assert semantic_tool.annotations.openWorldHint is True, (
+            "nc_semantic_search should have openWorldHint=True (queries external service)"
+        )
+
+
+async def test_annotation_consistency(nc_mcp_client: ClientSession):
+    """Verify annotation consistency across similar tools."""
+    tools = await nc_mcp_client.list_tools()
+
+    # Group tools by category
+    categories = {
+        "notes": [],
+        "calendar": [],
+        "contacts": [],
+        "webdav": [],
+        "tables": [],
+        "deck": [],
+        "cookbook": [],
+        "sharing": [],
+    }
+
+    for tool in tools.tools:
+        for category in categories:
+            if tool.name.startswith(f"nc_{category}_"):
+                categories[category].append(tool)
+
+    # Within each category, similar operations should have similar annotations
+    for category, category_tools in categories.items():
+        # All list/search/get operations should be read-only
+        read_ops = [
+            t
+            for t in category_tools
+            if any(op in t.name for op in ["list", "search", "get"])
+        ]
+        for tool in read_ops:
+            assert tool.annotations.readOnlyHint is True, (
+                f"{tool.name} is a read operation but not marked read-only"
+            )
+
+        # All delete operations should be destructive and idempotent
+        delete_ops = [t for t in category_tools if "delete" in t.name]
+        for tool in delete_ops:
+            assert tool.annotations.destructiveHint is True, (
+                f"{tool.name} is a delete operation but not marked destructive"
+            )
+            assert tool.annotations.idempotentHint is True, (
+                f"{tool.name} is a delete operation but not marked idempotent"
+            )
@@ -1671,7 +1671,7 @@ wheels = [

 [[package]]
 name = "mcp"
-version = "1.23.1"
+version = "1.22.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "anyio" },
@@ -1689,9 +1689,9 @@ dependencies = [
    { name = "typing-inspection" },
    { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/12/42/10c0c09ca27aceacd8c428956cfabdd67e3d328fe55c4abc16589285d294/mcp-1.23.1.tar.gz", hash = "sha256:7403e053e8e2283b1e6ae631423cb54736933fea70b32422152e6064556cd298", size = 596519, upload-time = "2025-12-02T18:41:12.807Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a3/a2/c5ec0ab38b35ade2ae49a90fada718fbc76811dc5aa1760414c6aaa6b08a/mcp-1.22.0.tar.gz", hash = "sha256:769b9ac90ed42134375b19e777a2858ca300f95f2e800982b3e2be62dfc0ba01", size = 471788, upload-time = "2025-11-20T20:11:28.095Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9f/9e/26e1d2d2c6afe15dfba5ca6799eeeea7656dce625c22766e4c57305e9cc2/mcp-1.23.1-py3-none-any.whl", hash = "sha256:3ce897fcc20a41bd50b4c58d3aa88085f11f505dcc0eaed48930012d34c731d8", size = 231433, upload-time = "2025-12-02T18:41:11.195Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/bb/711099f9c6bb52770f56e56401cdfb10da5b67029f701e0df29362df4c8e/mcp-1.22.0-py3-none-any.whl", hash = "sha256:bed758e24df1ed6846989c909ba4e3df339a27b4f30f1b8b627862a4bade4e98", size = 175489, upload-time = "2025-11-20T20:11:26.542Z" },
 ]

 [package.optional-dependencies]
@@ -1962,7 +1962,7 @@ wheels = [

 [[package]]
 name = "nextcloud-mcp-server"
-version = "0.49.0"
+version = "0.50.0"
 source = { editable = "." }
 dependencies = [
    { name = "aiosqlite" },
@@ -2027,7 +2027,7 @@ requires-dist = [
    { name = "jinja2", specifier = ">=3.1.6" },
    { name = "langchain-text-splitters", specifier = ">=1.0.0" },
    { name = "markdownify", specifier = ">=0.14.1" },
-    { name = "mcp", extras = ["cli"], specifier = ">=1.23,<1.24" },
+    { name = "mcp", extras = ["cli"], specifier = ">=1.22,<1.23" },
    { name = "openai", specifier = ">=2.8.1" },
    { name = "opentelemetry-api", specifier = ">=1.28.2" },
    { name = "opentelemetry-exporter-otlp-proto-grpc", specifier = ">=1.28.2" },
Author	SHA1	Message	Date
smithery-ai[bot]	3b48c904f5	Update README	2025-12-11 12:59:56 +00:00
github-actions[bot]	a60b88b80e	bump: version 0.49.2 → 0.50.0	2025-12-11 12:58:08 +00:00
Chris Coutinho	e31b4433a1	Merge pull request #387 from cbcoutinho/feat/add-mcp-tool-annotations feat: add MCP tool annotations for enhanced UX	2025-12-11 13:57:35 +01:00
Chris Coutinho	19183ad14a	fix: address PR review feedback Address all reviewer comments from PR #387: 1. ✅ Add unit tests for annotations (tests/server/test_annotations.py) - 10 comprehensive test functions validating all annotation patterns - Tests for titles, read-only, destructive, idempotent operations - Validates specific ADR-017 decisions (webdav write, semantic search) - Cross-category consistency checks 2. ✅ Fix nc_webdav_write_file idempotency classification - Changed from idempotentHint=False to idempotentHint=True - Rationale: Uses HTTP PUT without version control - Writing same content to same path = same end state (idempotent) 3. ✅ Fix semantic search openWorldHint inconsistency - Changed from openWorldHint=False to openWorldHint=True - Rationale: Consistent with other Nextcloud tools - Nextcloud is external to MCP server (indexed data is implementation detail) 4. ✅ Update ADR-017 with resolved decisions - Converted Open Questions to Resolved Questions - Added detailed rationale for webdav write and semantic search - Updated status from Proposed to Implemented - Added decision timeline with dates 5. ✅ Add MCP Tool Annotations guidelines to CLAUDE.md - Comprehensive section with code examples for all patterns - Key principles documented (idempotency, destructive, open world) - References ADR-017 for detailed rationale All OAuth tools verified to have proper annotations (oauth_tools.py lines 686-751).	2025-12-11 13:50:55 +01:00
Chris Coutinho	e1412320a7	feat: add MCP tool annotations for enhanced UX Add ToolAnnotations to all 105+ MCP tools across 13 modules to enable better client-side UX with human-readable titles and behavioral hints. Changes: - Add title and ToolAnnotations to all @mcp.tool() decorators - Apply correct idempotency classification per ADR-017 - Add destructiveHint for delete operations - Set openWorldHint=False for semantic search (internal data only) Modules updated: - OAuth (4 tools): Authentication and provisioning - Notes (7 tools): Note management - WebDAV (11 tools): File operations - Semantic (3 tools): Semantic search and RAG - Calendar (16 tools): Events and todos - Contacts (7 tools): Address book management - Sharing (5 tools): File/folder sharing - Tables (6 tools): Structured data - Deck (25 tools): Kanban board management - Cookbook (13 tools): Recipe management - News (8 tools): RSS feed reader Annotation patterns: - Read operations: readOnlyHint=True, openWorldHint=True - Create operations: idempotentHint=False, openWorldHint=True - Update operations: idempotentHint=False, openWorldHint=True - Delete operations: destructiveHint=True, idempotentHint=True, openWorldHint=True See docs/ADR-017-mcp-tool-annotations.md for rationale and implementation details. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>	2025-12-11 12:45:02 +01:00
Chris Coutinho	b9c94dfab0	Merge pull request #385 from cbcoutinho/renovate/docker.io-library-nginx-alpine chore(deps): update docker.io/library/nginx:alpine docker digest to 289deca	2025-12-10 12:56:34 +01:00
Chris Coutinho	6f43c09bd0	Merge pull request #386 from cbcoutinho/renovate/ghcr.io-astral-sh-uv-0.x chore(deps): update ghcr.io/astral-sh/uv docker tag to v0.9.17	2025-12-10 12:55:50 +01:00
Chris Coutinho	9e15e95c2b	Merge pull request #384 from cbcoutinho/renovate/anthropics-claude-code-action-digest chore(deps): update anthropics/claude-code-action digest to f0c8eb2	2025-12-10 12:54:21 +01:00
renovate-bot-cbcoutinho[bot]	1306c4cc9c	chore(deps): update ghcr.io/astral-sh/uv docker tag to v0.9.17	2025-12-10 11:10:37 +00:00
renovate-bot-cbcoutinho[bot]	f1247817d3	chore(deps): update docker.io/library/nginx:alpine docker digest to 289deca	2025-12-10 11:10:31 +00:00
renovate-bot-cbcoutinho[bot]	fdad5b85c9	chore(deps): update anthropics/claude-code-action digest to f0c8eb2	2025-12-10 11:10:26 +00:00
Chris Coutinho	39ee0b5973	Merge pull request #381 from cbcoutinho/renovate/docker.io-library-python-3.12-slim-trixie chore(deps): update docker.io/library/python:3.12-slim-trixie docker digest to 590cad7	2025-12-09 18:44:34 +01:00
github-actions[bot]	33675c8ae8	bump: version 0.49.1 → 0.49.2	2025-12-09 17:43:25 +00:00
Chris Coutinho	90d5e9887a	Merge pull request #383 from cbcoutinho/fix/bump fix: Update lockfile	2025-12-09 18:42:53 +01:00
Chris Coutinho	c3af591810	fix: Update lockfile	2025-12-09 18:42:03 +01:00
Chris Coutinho	44573366eb	build: Update lockfile	2025-12-09 15:49:25 +01:00
github-actions[bot]	edb0af2bda	bump: version 0.49.0 → 0.49.1	2025-12-09 14:46:43 +00:00
Chris Coutinho	7d5bb54b64	fix: Revert mcp version <1.23	2025-12-09 15:46:00 +01:00
Chris Coutinho	a18c63792a	Merge pull request #380 from cbcoutinho/renovate/docker.io-library-nextcloud-32.0.2 chore(deps): update docker.io/library/nextcloud:32.0.2 docker digest to 04cc195	2025-12-09 15:36:18 +01:00
renovate-bot-cbcoutinho[bot]	0b58707a49	chore(deps): update docker.io/library/python:3.12-slim-trixie docker digest to 590cad7	2025-12-09 11:07:35 +00:00
renovate-bot-cbcoutinho[bot]	0561b55af5	chore(deps): update docker.io/library/nextcloud:32.0.2 docker digest to 04cc195	2025-12-09 11:07:29 +00:00
Chris Coutinho	d785ed9054	Merge pull request #379 from cbcoutinho/renovate/astral-sh-setup-uv-7.x chore(deps): update astral-sh/setup-uv action to v7.1.5	2025-12-08 15:38:49 +01:00
renovate-bot-cbcoutinho[bot]	88fb8417fd	chore(deps): update astral-sh/setup-uv action to v7.1.5	2025-12-08 11:07:22 +00:00