Tool annotations, icons, content annotations (ADR 0006)

CHANGELOG.md

@@ -1,6 +1,38 @@
 # Revision history for mcp-server
 
-## 0.2.1.0 - ???
+## 0.2.0.1 - ???
+
+(Supersedes 0.2.0.0, which is **deprecated on Hackage**: it was published
+hours before this line landed and was never adopted, so rather than
+burning a major version on a release nobody used, 0.2.0.1 replaces it —
+including changes that would ordinarily demand a major bump. Anyone
+explicitly pinning the deprecated 0.2.0.0 should move here. The unreleased
+0.2.1.0 line below is folded in as well.)
+
+* Definition metadata (ADR 0006):
+    * `ToolAnnotations` — `readOnlyHint`/`destructiveHint`/`idempotentHint`/
+      `openWorldHint` behavioral hints (2025-03-26+) plus a title, all unset
+      by default (`defaultToolAnnotations`), carried on `ToolDefinition` and
+      driving client permission UX.
+    * `Icon` lists (2025-11-25+) on tool, prompt, resource and
+      resource-template definitions.
+    * Content `Annotations` (`audience`/`priority`/`lastModified`,
+      2025-03-26+) attached via the new `ContentAnnotated` wrapper, whose
+      annotations merge into the inner block's JSON (and parse back out).
+* New `WithOptions` derivations for all five derive families, taking
+  per-constructor `DefinitionOptions` (description, title, icons, tool
+  annotations, and **constructor-scoped field descriptions** — two
+  constructors can now describe a same-named field differently, fixing the
+  global-namespace wart of the flat description list, which remains
+  supported unchanged).
+* BREAKING: `ToolDefinition`, `PromptDefinition`, `ResourceDefinition` and
+  `ResourceTemplateDefinition` gain fields, and `Content` gains the
+  `ContentAnnotated` constructor. New smart constructors
+  (`mkToolDefinition`, `mkPromptDefinition`, `mkResourceDefinition`,
+  `mkResourceTemplateDefinition`) build definitions from required fields
+  only — construct through them and record-update, so future optional
+  fields stop breaking your code. All new JSON fields are omitted when
+  unset, so wire output for existing servers is unchanged.
 
 * Derived output schemas and structured content (ADR 0005): the new
   `deriveToolHandlerWithOutput` (and `...WithOutputDescription`) take a

README.md

@@ -244,6 +244,33 @@ data SimpleTool
 
 All parameter types must ultimately resolve to records with named fields to generate proper MCP schemas.
 
+#### Tool Annotations, Icons and Titles
+
+The `WithOptions` derivation variants take per-constructor
+`DefinitionOptions` — description, title, icons, behavioral annotations
+(which drive client permission UX, e.g. auto-approving read-only tools),
+and argument descriptions scoped to the constructor:
+
+```haskell
+tools = Just $(deriveToolHandlerWithOptions ''MyTool 'handleTool
+  [ ("Search", defaultDefinitionOptions
+      { optDescription = Just "Search the catalog"
+      , optToolAnnotations = Just defaultToolAnnotations
+          { toolReadOnlyHint = Just True, toolIdempotentHint = Just True }
+      , optIcons = [icon "https://example.com/search.png"]
+      , optFieldDescriptions = [("q", "Search terms")]
+      })
+  ])
+```
+
+Content blocks can carry annotations too (`audience`, `priority`,
+`lastModified`), attached with the `ContentAnnotated` wrapper:
+
+```haskell
+ContentAnnotated defaultAnnotations { annotationsPriority = Just 0.9 }
+                 (ContentText "important result")
+```
+
 ## Custom Descriptions
 
 You can provide custom descriptions for constructors and fields using the `*WithDescription` variants:

examples/Complete/Main.hs

@@ -69,7 +69,21 @@ main = do
     let prompts = $(derivePromptHandler ''MyPrompt 'handlePrompt)
         resources = $(deriveResourceHandler ''MyResource 'handleResource)
         templates = $(deriveResourceTemplates ''MyResource)
-        tools = $(deriveToolHandler ''MyTool 'handleTool)
+        -- Per-constructor options: descriptions, behavioral hints for
+        -- client permission UX, icons, and constructor-scoped argument
+        -- descriptions
+        tools = $(deriveToolHandlerWithOptions ''MyTool 'handleTool
+          [ ("SearchForProduct", defaultDefinitionOptions
+              { optDescription = Just "Search the product catalog"
+              , optToolAnnotations = Just defaultToolAnnotations
+                  { toolReadOnlyHint = Just True, toolIdempotentHint = Just True }
+              , optFieldDescriptions = [("q", "Search terms"), ("category", "Restrict to a category")]
+              })
+          , ("Checkout", defaultDefinitionOptions
+              { optToolAnnotations = Just defaultToolAnnotations
+                  { toolDestructiveHint = Just True }
+              })
+          ])
      in runMcpServerStdio
         McpServerInfo
             { serverName = "Complete Example MCP Server"

mcp-server.cabal

@@ -15,7 +15,7 @@ name: mcp-server
 -- PVP summary:     +-+------- breaking API changes
 --                  | | +----- non-breaking API additions
 --                  | | | +--- code changes with no API change
-version: 0.2.1.0
+version: 0.2.0.1
 -- A short (one-line) description of the package.
 synopsis: Library for building Model Context Protocol (MCP) servers
 -- A longer description of the package.
@@ -180,6 +180,7 @@ test-suite haskell-mcp-server-test
   other-modules:
     Spec.AdvancedDerivation
     Spec.BasicDerivation
+    Spec.DefinitionMetadata
     Spec.DerivedOutput
     Spec.GoldenWire
     Spec.JSONConversion

specs/ADR_0005_derived_output_schemas.md

@@ -1,6 +1,6 @@
 # ADR 0005: Derived output schemas and structured content
 
-- **Status**: Landed (0.2.1.0)
+- **Status**: Landed (0.2.0.1)
 - **Date**: 2026-08-01
 - **Depends on**: —
 

specs/ADR_0006_definition_metadata.md

@@ -1,6 +1,6 @@
 # ADR 0006: Tool annotations, icons, content annotations
 
-- **Status**: Proposed
+- **Status**: Landed (0.2.0.1)
 - **Date**: 2026-08-01
 - **Depends on**: —
 

specs/ROADMAP.md

@@ -8,19 +8,21 @@ value, not commitment.
 **Current state**: 0.2.0.0 is on Hackage (typed core, dual-era protocol
 support for 2024-11-05…2025-11-25 via `initialize` and stateless
 2026-07-28, resource templates, completions, change notifications with
-`subscriptions/listen`). 0.2.1.0 sits merged-but-unreleased (WAI
-application export, conformance corpus), soaking until enough accumulates.
+`subscriptions/listen`) but is deprecated there in favor of the pending
+line: 0.2.0.1 sits merged-but-unreleased (WAI application export,
+conformance corpus, and Batch 1: derived output schemas, definition
+metadata), soaking until released. 0.2.0.1 knowingly supersedes the
+never-adopted 0.2.0.0 in place rather than burning a major version.
 
-## Batch 1 — complete the typed core *(candidates to join the pending release)*
+## Batch 1 — complete the typed core *(landed)*
 
-Both are additive (PVP minor) and could ship with 0.2.1.x.
+Both landed in the pending 0.2.0.1.
 
-1. [ADR_0005 — Derived output schemas and structured content](ADR_0005_derived_output_schemas.md).
-   The highest-leverage item: finishes the library's thesis (typed in,
-   typed out) and is a genuine differentiator.
-2. [ADR_0006 — Tool annotations, icons, content annotations](ADR_0006_definition_metadata.md).
-   Cheap metadata that materially improves how clients treat our servers
-   (read-only/destructive hints drive permission UX).
+1. [ADR_0005 — Derived output schemas and structured content](ADR_0005_derived_output_schemas.md) — **Landed**.
+2. [ADR_0006 — Tool annotations, icons, content annotations](ADR_0006_definition_metadata.md) — **Landed**
+   (the definition-datatype extensions are breaking; they ship anyway in
+   0.2.0.1 because the only affected release, 0.2.0.0, is deprecated with
+   zero adopters).
 
 ## Batch 2 — long-running tools