spec: Define adapter-scoped tool naming convention and annotation requirements

[mickdarling]

Summary

Define how MCPAQL adapters name their tools to prevent collisions when multiple adapters run simultaneously, and specify annotation requirements for rich client display.

Problem

Every MCPAQL adapter currently exposes the same 5 tool names: mcp_aql_create, mcp_aql_read, mcp_aql_update, mcp_aql_delete, mcp_aql_execute. When multiple adapters are running (Apple Mail + GitHub + Slack), clients see multiple identically-named tools with no way to distinguish them. The LLM must guess which mcp_aql_read to call.

This is especially visible in Claude Desktop where only the tool name is prominently displayed, not the MCP server config name.

Proposal

1. Adapter-Scoped Tool Name Convention

The spec MUST define a tool naming template that includes the adapter identity. The canonical pattern:

{adapter}_mcpaql_{endpoint}

Examples:

• apple_mail_mcpaql_read
• apple_mail_mcpaql_create
• github_api_mcpaql_read
• github_api_mcpaql_execute

The mcpaql segment is the protocol brand — not aql (which collides with other query languages). The full mcpaql name MUST be used.

The adapter schema defines the tool name pattern:

tool_names:
  pattern: "{adapter}_mcpaql_{endpoint}"

Template variables:

• {adapter} — the adapter's name field, snake_cased
• {endpoint} — one of: create, read, update, delete, execute

Single-adapter deployments MAY use the bare pattern mcpaql_{endpoint} (no adapter prefix) for backward compatibility, but this SHOULD be opt-in, not the default.

2. Annotation Requirements

Adapters MUST set the following MCP tool annotations:

Annotation	Requirement	Example
title	MUST — human-readable adapter + endpoint name	"Apple Mail — Read"
readOnlyHint	MUST — true for READ, false for others	true
destructiveHint	MUST — true for DELETE and EXECUTE, false for others	true
idempotentHint	SHOULD — true for READ, false for CREATE/EXECUTE	true
openWorldHint	SHOULD — true for HTTP adapters, false for local/native	false

The title annotation is the primary display mechanism for rich clients. It SHOULD follow the pattern: "{Adapter Display Name} — {Endpoint}".

3. Generator Updates

The adapter generator MUST:

1. Read tool_names.pattern from the adapter schema (default: "{adapter}_mcpaql_{endpoint}")
2. Generate tool registrations using the resolved names
3. Set all required annotations on each tool
4. Include the adapter display name in the title annotation

4. Introspection

The introspect operation MUST include adapter identity:

{
  "success": true,
  "data": {
    "_protocol": {
      "version": "1.0.0",
      "mode": "crude",
      "adapter": "apple-mail",
      "display_name": "Apple Mail"
    },
    "operations": [...]
  }
}

Client Annotation Support (Current Landscape)

Client	title	readOnlyHint	destructiveHint	Notes
Claude Code	Supported	Active (parallelization)	Active (confirmation)	Most mature
Claude Desktop	Supported	Active (auto-approval)	Active (confirmation)	Primary target
Cursor	Unknown	Unknown	Unknown	MCP support confirmed
Windsurf	Unknown	Unknown	Unknown	MCP support confirmed
Zed	Unknown	Unknown	Unknown	MCP support confirmed
Continue	Unknown	Unknown	Unknown	MCP support confirmed

Branding Note

The protocol name is MCPAQL, not AQL. Tool names MUST use mcpaql (e.g., apple_mail_mcpaql_read), not aql (e.g., apple_mail_aql_read). AQL collides with ArangoDB's query language and other established uses.

Acceptance Criteria

• Tool naming template defined in adapter element type spec
• {adapter}_mcpaql_{endpoint} as default pattern
• Annotation requirements specified (title, readOnlyHint, destructiveHint minimum)
• Generator updated to use naming template and set annotations
• Introspection includes adapter identity
• Backward compatibility guidance for existing mcp_aql_* tools

References

• Adapter Element Type: docs/adapter/element-type.md
• Generator Spec: docs/adapter/generator.md
• MCP Tool Annotations: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
• MCP Annotations Blog: https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/