feat: support MCP tool hints mapped to ToolAnnotations

[jlouvel]

---

Related Issue

Closes #200

---

What does this PR do?

Adds support for MCP tool hints — optional behavioral metadata on tools that maps to ToolAnnotations in the MCP protocol (spec 2025-11-25).

Capability authors can now declare hints on any MCP tool with four advisory properties:

• readOnly — tool does not modify its environment
• destructive — tool may perform destructive updates
• idempotent — repeating the call has no additional effect
• openWorld — tool interacts with external entities

These are YAML-facing names (no Hint suffix — the hints parent provides context). On the wire, they map to the MCP spec field names (readOnlyHint, destructiveHint, etc.) inside the annotations object.

The existing label field continues to map to both Tool.title and annotations.title.

Example YAML:

tools:
  - name: get-current-weather
    description: "Retrieve current weather conditions"
    hints:
      readOnly: true
      openWorld: true
    call: weather-api.get-current

Changes by layer:

• Schema: new McpToolHints definition + hints property on McpTool
• Spec POJO: new McpToolHintsSpec class + hints field on McpServerToolSpec
• Engine: McpServerAdapter.buildMcpTool() maps hints → McpSchema.ToolAnnotations; ProtocolDispatcher.handleToolsList() emits annotations in the wire response
• Docs: Specification-Schema, Tutorial Part 1, FAQ, design-guidelines, wrap-api-as-mcp, SKILL.md
• Example: skill-adapter.yml updated with hints on get-current-weather

---

Tests

• McpToolHintsIntegrationTest (7 tests):

  • YAML deserialization of partial and full hints
  • Backward compat: tool without hints has null spec
  • buildToolAnnotations() mapping: hints + label, label-only, neither
  • Wire format roundtrip: tools/list response includes annotations with correct MCP field names, omits absent hints, omits annotations entirely when no hints or label

• All 395 existing tests pass (0 failures, 0 errors).

---

Checklist

• CI is green (build, tests, schema validation, security scans)
• Rebased on latest main
• Small and focused — one concern per PR
• Commit messages follow Conventional Commits

---

Agent Context (optional)

agent_name: GitHub Copilot
llm: Claude Opus 4.6
tool: VS Code Chat
confidence: high
source_event: user request to support MCP ToolAnnotations per spec 2025-11-25
discovery_method: user_report
review_focus: McpServerAdapter.java:155-180, ProtocolDispatcher.java:146-192, naftiko-schema.json (McpToolHints def)