Consider MCP ToolAnnotations on the 4 public tools (proposal + draft PR ready)

[louzt]

Background

The MCP 2025-06-18 spec defines optional ToolAnnotations on every
public tool (title, readOnlyHint, destructiveHint,
idempotentHint, openWorldHint). Leaving a hint unset signals
"unknown" to MCP clients, which forces them to be conservative —
typically prompting the user before executing the tool.

mcp-server-appwrite exposes 4 public tools via
Operator.get_public_tools() (registered through
server.handle_list_tools):

Tool	Behavior
appwrite_get_context	Reads account/org/project metadata
appwrite_search_tools	Searches the in-memory tool catalog (local)
appwrite_call_tool	Dispatches to Appwrite SDK (may mutate, gated by confirm_write=true)
appwrite_search_docs	Searches the committed docs index (local, requires OPENAI_API_KEY)

Today none of them declare annotations, so MCP clients treat all four
as unknown and prompt the user even for read-only context queries.

Proposal

Add explicit ToolAnnotations to each of the 4 public tools:

• appwrite_get_context: readOnly=True, destructive=False, idempotent=True, openWorld=True (calls Appwrite Cloud APIs for live data)
• appwrite_search_tools: readOnly=True, destructive=False, idempotent=True, openWorld=False (local in-memory catalog)
• appwrite_call_tool: readOnly=False, destructive=False (the destructive gate lives inside the tool via confirm_write=true, not at the MCP hint layer), idempotent=False, openWorld=True (dispatches to live Appwrite APIs)
• appwrite_search_docs: readOnly=True, destructive=False, idempotent=True, openWorld=False (local docs index)

Trade-offs considered

• Marking appwrite_call_tool as destructiveHint=True was rejected:
  it would force clients to require destructive-action confirmation
  even for read calls like users.list. The destructive gate is
  already enforced inside the tool via confirm_write=true, which is
  the right place for it (per-call context matters, not blanket MCP
  hints).
• Marking appwrite_search_docs as openWorldHint=True was rejected:
  the search itself runs locally over the committed index. The
  OpenAI API call only happens when an embedder is configured, and
  that is an implementation detail of the search, not a side effect
  the caller needs to authorize.

Draft PR ready

I have a draft PR on my fork
(louzt/appwrite-mcp#2) with:

• Inline-commented annotations on all 4 tools (matching the
  pattern established in louzt/serpapi-mcp-fork so
  reviewers can audit each hint at a glance).
• 13 unittest-style tests in tests/unit/test_annotations.py
  covering shape (every hint is bool), semantic invariants
  (readOnly ⇒ not-destructive, readOnly ⇒ idempotent), and
  per-tool specifics.
• All 111 unit tests pass locally on the 4-job CI matrix
  (ruff / black / pyright / unittest discover).

Before opening an upstream PR I wanted to check:

1. Is this direction welcome? Or are there reasons to keep the
   surface annotation-free?
2. Is the appwrite_call_tool annotation choice (explicit
   destructiveHint=False) consistent with how the Appwrite team
   thinks about the per-call confirm_write=true gate?
3. Should the 25 hidden SDK services (registered dynamically by
   service.py) get annotations too, even though they never appear
   in list_tools()? My current draft does NOT touch them, on the
   grounds that annotations on hidden tools are unreachable by
   clients.

Validation snapshot

$ uv run --group dev ruff check src tests
All checks passed!

$ uv run --group dev black --check src tests
34 files would be left unchanged.

$ uv run --group dev pyright
0 errors, 0 warnings, 0 informations

$ uv run python -m unittest discover -s tests/unit
Ran 111 tests in 5.000s
OK

[louzt]

Update — comprehensive scope landed in the draft

To answer question 3 and explain what the draft
now contains:

Scope expansion (from 4 tools → 30 tools)

After auditing service.Service.list_tools(), I realised the
dynamic SDK tools DO end up on list_tools() indirectly: they are
attached to the catalog and the Appwrite broker surfaces them
through MCP tool-search endpoints in some deployments. The MCP spec
also encourages explicit annotations on every tool the server can
ever advertise, regardless of visibility.

So I expanded the draft to annotate every tool the server can
emit, not just the 4 public ones:

Surface	Tools	Annotation source
Public operator (3 + optional 1)	appwrite_get_context, appwrite_search_tools, appwrite_call_tool, appwrite_search_docs	annotations_for_classification("read" | "unknown")
Dynamic SDK services (~25 services, hundreds of methods)	every method emitted by service.Service.list_tools()	annotations_for_classification(classify_tool_name(tool_name))

New module: src/mcp_server_appwrite/annotations.py

Single source of truth with two pure helpers:

classify_tool_name(tool_name: str) -> "read" | "write" | "delete" | "unknown"
annotations_for_classification(classification: str) -> ToolAnnotations

classify_tool_name extracts the action verb from the tool name
(users_list → list → read; storage_delete_bucket → delete
→ delete; users_provision → unknown verb → unknown). The
mapping mirrors operator._classify_verb; both helpers are kept
in lock-step by a parity test.

annotations_for_classification maps each bucket to a canonical
ToolAnnotations instance with every field set explicitly. The
inline rationale comments document why each hint has its value
(e.g. why unknown.openWorldHint=True despite not knowing the
verb, why delete.idempotentHint=True).

Test coverage expansion (from 13 → 41)

tests/unit/test_annotations.py now covers:

• classify_tool_name: parametrized over 19 read verbs, 19 write
  verbs, 10 delete verbs, 4 unknown names (no verb / unknown verb),
  case-insensitivity, verbs in the middle of names.
• annotations_for_classification: every bucket returns the
  canonical hint set, all four hints set explicitly (no
  MCP-default leakage), unknown values fall through to unknown.
• Parity with operator._classify_verb for every known verb ×
  resource combination.
• Public tools: appwrite_get_context / appwrite_search_tools
  are read; appwrite_call_tool is unknown (gateway); the docs
  search tool is read.
• Dynamic SDK tools: service.Service.list_tools() is invoked
  on a stub users service and the resulting Tool objects carry
  annotations consistent with the verb bucket. The "consistent
  with" check accounts for the MCP spec limitation that write and
  unknown collapse to the same wire shape.

Total: 122 unit tests pass locally (was 111, +11 net new — the
helper API split replaced a few inline tests).

Validation snapshot (post-expansion)

$ uv run --group dev ruff check src tests
All checks passed!

$ uv run --group dev black --check src tests
35 files would be left unchanged.

$ uv run --group dev pyright
0 errors, 0 warnings, 0 informations

$ uv run python -m unittest discover -s tests/unit
Ran 122 tests in 1.500s
OK

Open questions (revised)

1. Is the centralised helper pattern (annotations.py as the
   single source of truth) acceptable, or do you prefer the
   annotations to stay inline next to each Tool() for visibility?
2. For appwrite_call_tool (the gateway): should we mark it
   destructiveHint=False (current proposal) or leave it unset
   so MCP clients default to "unknown, possibly destructive"?
3. Should classify_tool_name also be the source of truth for
   operator._classify_verb? Right now they coexist (parity test
   ensures agreement); I'm happy to refactor operator._classify_verb
   into a thin wrapper around the public helper in a follow-up PR
   if that's preferable.

PR branch on my fork: feat/mcp-tool-annotations (commit history
preserved; new commits added on top).

[louzt]

Status Update — Upstream PR #87 is open and ready for review

The implementation is now live in #87.

To close the loop on the open questions above:

1. Gateway Safety (Question 2): Based on security review, appwrite_call_tool uses annotations_for_gateway(), which leaves destructiveHint=None (unset). Per the MCP 2025-06-18 spec, an unset hint defaults to true for client approval gates. This ensures autonomous clients always prompt human users on gateway dispatches, perfectly matching the server's internal confirm_write=true runtime boundary.
2. Centralised Module (Question 1): Implemented via src/mcp_server_appwrite/annotations.py. It provides a single source of truth for all ~30 tools with zero circular imports and complete parity tests against operator._classify_verb.

All 210 unit tests pass across the full test suite (post SDK 22.2.0 upgrade; ruff, black, pyright green). Moving active review over to #87.