feat(10-02b): add toolDescription to InProcessTool + toolSchemas() projection

Adds the substrate that the production fix at App/AppDelegate.swift:1274
needs to source the tool catalog from the in-process registry instead of
the hardcoded empty array.

Protocol change:
- InProcessTool gains `var toolDescription: String { get }` — a
  human-readable one-line description surfaced in the Anthropic / Ollama
  tools[] payload's `description` field. Named `toolDescription` (not
  `description`) to avoid colliding with CustomStringConvertible.

All 7 production InProcessTool implementations updated with descriptions
calibrated to drive correct tool selection by the model:
- list_audio_devices, get_active_audio_route, get_self_state,
  list_camera_devices (Phase 10-01 self-knowledge tools)
- search_memory, forget_fact, search_conversation (Phase 7 memory tools)

Registry change:
- InProcessToolRegistry.toolSchemas() projects every registered tool to
  a ToolSchema(name, description, inputSchema) suitable for the LLM
  request body. Returns name-sorted for prompt-cache determinism.
- Adds AgentCore import to InProcessToolRegistry for the ToolSchema type.

Test coverage:
- InProcessToolRegistrySchemasTests asserts all 7 tools project
  correctly with non-empty descriptions and inputSchema bytes.
- All 85 existing MCP tests pass unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
james.maesandClaude Opus 4.7 committed 2026-05-07 07:28:20 -05:00
1 parent 260350b3dc
commit c5c5072b5d
10 files changed
+164

No files matched your search

@@ -11,6 +11,13 @@ public protocol ForgetFactDispatching: Sendable {
public struct ForgetFactTool: InProcessTool {
public let name: String = "forget_fact"
public let toolDescription: String = """
Forgets a single previously-stored fact by its numeric factId (obtained \
from search_memory hits). Destructive — closes the fact's valid_to \
interval and sets forgotten_at; the row is NEVER deleted. ALWAYS \
confirmation-gated through the HUD's confirmation prompt. Call this \
tool only when the user explicitly asks Jarvis to forget something.
"""
public let requiresConfirmation: Bool = true
public var schemaJSON: Data {
@@ -46,6 +46,13 @@ public struct ActiveAudioRoute: Sendable, Codable, Equatable {
public struct GetActiveAudioRouteTool: InProcessTool {
public let name: String = "get_active_audio_route"
public let toolDescription: String = """
Returns the microphone and speaker that the running voice loop is \
currently bound to (input + output device names and UIDs, sample rate, \
channel count, and AEC variant). Call this tool when the user asks \
what mic, headset, or speakers Jarvis is using right now — it reflects \
the live AudioGraph route, not the system default.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data { Self.schema }
@@ -57,6 +57,14 @@ public struct SelfState: Sendable, Codable, Equatable {
public struct GetSelfStateTool: InProcessTool {
public let name: String = "get_self_state"
public let toolDescription: String = """
Returns a point-in-time snapshot of Jarvis's own runtime state — app \
version, build mode (debug/release), pid, uptime, active LLM provider \
and model, TTS tier, STT backend, wake-word mute flag, and current \
voice-loop state. Call this tool when the user asks what model is \
running, whether wake-word is muted, how long the app has been up, or \
any question about Jarvis's own configuration.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data { Self.schema }
@@ -10,6 +10,12 @@ import Foundation
public protocol InProcessTool: Sendable {
/// Tool name as exposed to the LLM.
var name: String { get }
/// Human-readable one-line description for the LLM. Plan 10-02b /
/// B-01: surfaced into the Anthropic / Ollama tools[] payload as the
/// `description` field so the model knows when to call this tool. Use
/// `toolDescription` (not `description`) to avoid colliding with
/// `CustomStringConvertible.description` on conforming types.
var toolDescription: String { get }
/// JSON Schema bytes used by the tool catalog when ListTools is called.
var schemaJSON: Data { get }
/// D-02: forget_fact is destructive and must always confirmation-gate
@@ -1,4 +1,5 @@
import Foundation
import AgentCore
/// Holds [String: any InProcessTool] and dispatches CallTool requests by name.
/// AppDelegate (Plan 07-06) builds one and injects it alongside the existing
@@ -27,4 +28,21 @@ public actor InProcessToolRegistry {
}
return try await tool.call(args: args)
}
/// Plan 10-02b / B-01: project every registered in-process tool to a
/// `ToolSchema` (name + human-readable description + JSON-schema bytes)
/// suitable for the Anthropic / Ollama tools[] payload. Returned in
/// stable name-sorted order so request bodies are deterministic across
/// turns (helpful for prompt caching and snapshot tests).
public func toolSchemas() -> [ToolSchema] {
tools.values
.map { tool in
ToolSchema(
name: tool.name,
description: tool.toolDescription,
inputSchema: tool.schemaJSON
)
}
.sorted { $0.name < $1.name }
}
}
@@ -50,6 +50,14 @@ public struct AudioDeviceEntry: Sendable, Codable, Equatable {
public struct ListAudioDevicesTool: InProcessTool {
public let name: String = "list_audio_devices"
public let toolDescription: String = """
Lists every audio I/O device on the user's Mac (one entry per direction — \
inputs and outputs as separate rows). Each entry includes name, UID, \
sample rate, channel count, default-device flag, and active flag. Call \
this tool when the user asks about microphones, speakers, headphones, or \
audio devices in general — never speculate or tell them to open System \
Settings.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data { Self.schema }
@@ -42,6 +42,13 @@ public struct CameraDeviceEntry: Sendable, Codable, Equatable {
public struct ListCameraDevicesTool: InProcessTool {
public let name: String = "list_camera_devices"
public let toolDescription: String = """
Lists every camera device the host exposes (built-in FaceTime camera, \
Continuity/external cameras, etc.) with localized name, unique ID, \
connection state, and position (front/back/external/unknown). Call this \
tool when the user asks what cameras are available — enumeration is \
metadata-only and does NOT trigger the camera permission prompt.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data { Self.schema }
@@ -26,6 +26,13 @@ public struct SearchConversationTurn: Sendable, Codable, Equatable {
public struct SearchConversationTool: InProcessTool {
public let name: String = "search_conversation"
public let toolDescription: String = """
Returns the most recent N turns of the current chat session (user + \
assistant messages with role, content, timestamp, and source). \
Session-scoped — does NOT search across past sessions. Call this tool \
when the user references something said earlier in this conversation \
that may have scrolled out of the visible context window.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data {
@@ -27,6 +27,14 @@ public struct SearchMemoryHit: Sendable, Codable, Equatable {
public struct SearchMemoryTool: InProcessTool {
public let name: String = "search_memory"
public let toolDescription: String = """
Searches Jarvis's long-term memory store for facts the user has \
previously shared (preferences, names, dates, project context). \
Hybrid keyword (FTS5) + semantic (vec0) search across all sessions; \
returns up to k hits ranked by reciprocal-rank fusion. Call this tool \
when the user references something they told Jarvis earlier or asks \
"do you remember…" — never claim to remember without searching first.
"""
public let requiresConfirmation: Bool = false
public var schemaJSON: Data {
@@ -0,0 +1,88 @@
import XCTest
import AgentCore
@testable import JarvisMCP
/// Plan 10-02b / B-01: assert `InProcessToolRegistry.toolSchemas()`
/// projects every registered in-process tool to a `ToolSchema` suitable for
/// the Anthropic / Ollama tools[] payload, including the new
/// `toolDescription` field that the substrate fix introduced. Catches
/// regressions where a new tool is added without a description (otherwise
/// the description would silently default and the model would lose
/// context about when to call it).
final class InProcessToolRegistrySchemasTests: XCTestCase {
actor StubHybrid: HybridSearchDispatching {
func searchFacts(query: String, k: Int, triggerTurnId: Int64) async throws -> [SearchMemoryHit] { [] }
}
actor StubForget: ForgetFactDispatching {
func forgetFact(id: Int64, triggerTurnId: Int64) async throws -> Bool { false }
}
actor StubHistory: SessionHistoryDispatching {
func recentTurns(sessionId: String, limit: Int) async throws -> [SearchConversationTurn] { [] }
}
actor StubAudio: AudioDeviceListing {
func listAudioDevices() async throws -> [AudioDeviceEntry] { [] }
}
actor StubRoute: ActiveAudioRouteDispatching {
func getActiveAudioRoute() async throws -> ActiveAudioRoute? { nil }
}
actor StubSelfState: SelfStateDispatching {
func getSelfState() async -> SelfState {
SelfState(appName: "Jarvis", appVersion: "test", buildMode: "debug",
pid: 0, uptimeSeconds: 0, llmProvider: "anthropic",
llmModel: "claude-opus-4-7", ttsTier: "tier1",
sttBackend: "speechAnalyzer", wakeWordMuted: false,
voiceLoopState: "idle")
}
}
actor StubCamera: CameraDeviceListing {
func listCameraDevices() async throws -> [CameraDeviceEntry] { [] }
}
/// Registers all 7 production in-process tools and asserts
/// `toolSchemas()` returns one ToolSchema per tool, sorted by name,
/// with non-empty `description` and matching `inputSchema` bytes.
func test_toolSchemas_projectsAllRegisteredTools() async throws {
let registry = InProcessToolRegistry()
await registry.register(SearchMemoryTool(dispatcher: StubHybrid()))
await registry.register(ForgetFactTool(dispatcher: StubForget()))
await registry.register(SearchConversationTool(dispatcher: StubHistory()))
await registry.register(ListAudioDevicesTool(dispatcher: StubAudio()))
await registry.register(GetActiveAudioRouteTool(dispatcher: StubRoute()))
await registry.register(GetSelfStateTool(dispatcher: StubSelfState()))
await registry.register(ListCameraDevicesTool(dispatcher: StubCamera()))
let schemas = await registry.toolSchemas()
// 7 tools registered, 7 schemas projected — no silent loss.
XCTAssertEqual(schemas.count, 7,
"toolSchemas() lost a tool — registered 7, got \(schemas.count)")
// Sorted by name (deterministic for prompt-cache stability).
XCTAssertEqual(schemas.map(\.name), schemas.map(\.name).sorted(),
"toolSchemas() must return name-sorted schemas")
// Every schema has a non-empty description (B-01: model needs the
// description to know WHEN to call each tool).
for schema in schemas {
XCTAssertFalse(schema.description.isEmpty,
"tool \(schema.name) has empty description — model has no signal for when to call it")
}
// Every schema's inputSchema is non-empty JSON bytes.
for schema in schemas {
XCTAssertFalse(schema.inputSchema.isEmpty,
"tool \(schema.name) has empty inputSchema bytes")
}
// Spot-check: every expected tool name is present.
let names = Set(schemas.map(\.name))
let expected: Set<String> = [
"search_memory", "forget_fact", "search_conversation",
"list_audio_devices", "get_active_audio_route", "get_self_state",
"list_camera_devices",
]
XCTAssertEqual(names, expected,
"tool name set does not match expected production catalog")
}
}