chat: use structured outputs for SearchBookContent MCP tool (#1079)

## Summary

Improves structured output consistency across the AI chat RAG pipeline
by converting `SearchBookContent` — the primary semantic vector search
tool — to use the same hybrid structured content pattern already
established by `FindBookHelpForDiagnostic` and `SearchListingsByCode`.

## Changes

### `SearchBookContent` converted to structured output
`SearchBookContent` was the only major RAG tool still returning plain
text. It now returns a `CallToolResult` with:
- `UseStructuredContent = true` and `OutputSchemaType =
typeof(SearchBookContentResult)`
- `McpToolResultFormatter.GetModelInput()` will now return the JSON
`StructuredContent` to the model instead of the formatted text,
consistent with all other structured tools
- The human-readable text is preserved as the first `Content` block for
MCP clients that display it

### "No results" semantics fixed
The zero-results path previously returned
`McpToolResultFactory.CreateError()` (`IsError = true`). Zero results
from a search query is a **valid outcome**, not a tool failure. It now
returns `CreateHybridResult` with an empty `Matches: []` list, so the
model always receives well-typed JSON conforming to the schema.

Validation failures (empty query, query too long, AI service not
configured) remain correctly modeled as errors.

### New structured result types
Added to `McpToolResults.cs`:
- `SearchBookContentMatchResult` — one vector search hit (score, chapter
number, heading, text chunk)
- `SearchBookContentResult` — wrapper with `Matches` list; this is the
advertised output schema

### `OutputSchemaType` made explicit on all `UseStructuredContent` tools
Five tools that had `UseStructuredContent = true` but no
`OutputSchemaType` were updated:
`GetChapterList`, `GetChapterSections`, `GetDirectContentUrl`,
`GetNavigationContext`, `GetChapterSummary`.

The MCP SDK already auto-infers the output schema from the concrete
return type (confirmed by pre-existing integration tests), so this is
redundant but makes the intended schema contract explicit at the
declaration site — consistent with how `FindBookHelpForDiagnostic` and
`SearchListingsByCode` are declared.

### Contract test updated

`McpToolContractTests.McpToolsList_StructuredAndHybridTools_AdvertiseOutputSchema`
now asserts that `search_book_content` advertises an `outputSchema`,
alongside the other structured tools.

## What was NOT changed (and why)

- **Main chat response format** —
`ResponseTextFormat.CreateJsonSchemaFormat()` does not exist in OpenAI
SDK 2.7.0 for the Responses API. Schema-enforced output on the streaming
text response isn't possible without switching to the Chat Completions
API, and would break markdown rendering anyway. Both subagents agreed
this is correct.
- **`strictModeEnabled: true` on tool input registration** — Already
correct in `AIChatService.cs`, untouched.
- **Plain-text tools** (`LookupConcept`, `CheckTopicCoverage`,
`FindRelatedSections`, etc.) — These return prose-heavy navigation
summaries where structured content wouldn't add value for the model.

## Testing

- ✅ Solution builds: 0 errors, 0 warnings
- ✅ All 11 chat unit tests pass
- ✅ Contract test updated to cover `search_book_content` schema
advertisement

Author: BenjaminMichaelis

EssentialCSharp.Web.Tests/McpToolContractTests.cs

@@ -37,6 +37,7 @@ public async Task McpToolsList_StructuredAndHybridTools_AdvertiseOutputSchema()
         await Assert.That(GetTool(tools, "get_chapter_summary").TryGetProperty("outputSchema", out _)).IsTrue();
         await Assert.That(GetTool(tools, "search_listings_by_code").TryGetProperty("outputSchema", out _)).IsTrue();
         await Assert.That(GetTool(tools, "find_book_help_for_diagnostic").TryGetProperty("outputSchema", out _)).IsTrue();
+        await Assert.That(GetTool(tools, "search_book_content").TryGetProperty("outputSchema", out _)).IsTrue();
 
         await Assert.That(GetTool(tools, "get_section_content").TryGetProperty("outputSchema", out _)).IsFalse();
         await Assert.That(GetTool(tools, "get_listing_source_code").TryGetProperty("outputSchema", out _)).IsFalse();

EssentialCSharp.Web/Models/McpToolResults.cs

@@ -1,5 +1,14 @@
 namespace EssentialCSharp.Web.Models;
 
+public sealed record SearchBookContentMatchResult(
+    double Score,
+    int? ChapterNumber,
+    string? Heading,
+    string ChunkText);
+
+public sealed record SearchBookContentResult(
+    IReadOnlyList<SearchBookContentMatchResult> Matches);
+
 public sealed record BookTocItemResult(
     string Key,
     string Title,

EssentialCSharp.Web/Tools/BookContentTool.cs

@@ -136,13 +136,13 @@ public async Task<string> GetListingWithContext(
             explanations).ToMcpString();
     }
 
-    [McpServerTool(Title = "Get Navigation Context", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true),
+    [McpServerTool(Title = "Get Navigation Context", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(NavigationContextToolResult)),
      Description("Get the navigation context for a book section: its breadcrumb path, the previous and next sections, its parent section, and its sibling sections. Useful for understanding where a section sits in the book's structure.")]
     public NavigationContextToolResult GetNavigationContext(
         [Description("The section slug/key (e.g., 'hello-world'). Use GetChapterSections to get valid slugs.")] string sectionKey) =>
         _bookToolQueryService.GetNavigationContext(sectionKey);
 
-    [McpServerTool(Title = "Get Chapter Summary", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true),
+    [McpServerTool(Title = "Get Chapter Summary", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(ChapterSummaryToolResult)),
      Description("Get a structural overview of a book chapter: its top-level section headings in reading order, and the coding guidelines associated with that chapter. Useful for understanding what a chapter covers before diving in.")]
     public ChapterSummaryToolResult GetChapterSummary(
         [Description("The chapter number (e.g., 5 for Chapter 5).")] int chapter) =>

EssentialCSharp.Web/Tools/BookSearchTool.cs

@@ -29,57 +29,72 @@ public BookSearchTool(
         _bookToolQueryService = bookToolQueryService;
     }
 
-    [McpServerTool(Title = "Search Book Content", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false),
+    [McpServerTool(Title = "Search Book Content", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(SearchBookContentResult)),
      Description("Search the Essential C# book content using semantic vector search. Returns relevant text chunks with chapter and heading context. Use this to find information about C# programming concepts covered in the book.")]
-    public async Task<string> SearchBookContent(
+    public async Task<CallToolResult> SearchBookContent(
         [Description("The search query describing the C# concept or topic to find in the book.")] string query,
         [Description("Number of results to return (1–10). Use a higher value for broad topics or comprehensive research; lower for quick lookups.")] int maxResults = AISearchService.DefaultSearchTop,
         CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrWhiteSpace(query))
         {
-            return "Query must not be empty.";
+            return McpToolResultFactory.CreateError("Query must not be empty.");
         }
         if (query.Length > 500)
         {
-            return "Query is too long (maximum 500 characters).";
+            return McpToolResultFactory.CreateError("Query is too long (maximum 500 characters).");
         }
 
         if (_SearchService is null)
         {
-            return "Book search is not available in this environment (AI services are not configured).";
+            return McpToolResultFactory.CreateError("Book search is not available in this environment (AI services are not configured).");
         }
 
-        List<SearchBookContentMatchTextResult> matches = (await _SearchService.ExecuteVectorSearch(
-                query,
-                top: maxResults,
-                cancellationToken: cancellationToken))
+        var rawResults = await _SearchService.ExecuteVectorSearch(
+            query,
+            top: maxResults,
+            cancellationToken: cancellationToken);
+
+        if (rawResults.Count == 0)
+        {
+            return McpToolResultFactory.CreateHybridResult(
+                "No results found for the given query.",
+                new SearchBookContentResult([]));
+        }
+
+        List<SearchBookContentMatchTextResult> textMatches = rawResults
             .Select(result => new SearchBookContentMatchTextResult(
                 result.Score ?? 0,
                 result.Record.ChapterNumber,
                 result.Record.Heading,
                 result.Record.ChunkText))
             .ToList();
 
-        if (matches.Count == 0)
-        {
-            return "No results found for the given query.";
-        }
+        SearchBookContentResult structuredResult = new(
+            rawResults
+                .Select(result => new SearchBookContentMatchResult(
+                    result.Score ?? 0,
+                    result.Record.ChapterNumber,
+                    result.Record.Heading,
+                    result.Record.ChunkText))
+                .ToList());
 
-        return new SearchBookContentTextResult(matches).ToMcpString();
+        return McpToolResultFactory.CreateHybridResult(
+            new SearchBookContentTextResult(textMatches).ToMcpString(),
+            structuredResult);
     }
 
-    [McpServerTool(Title = "Get Chapter List", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true),
+    [McpServerTool(Title = "Get Chapter List", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(ChapterListToolResult)),
      Description("Get the table of contents for the Essential C# book, listing all chapters and their sections with navigation links.")]
     public ChapterListToolResult GetChapterList() => _bookToolQueryService.GetChapterList();
 
-    [McpServerTool(Title = "Get Chapter Sections", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true),
+    [McpServerTool(Title = "Get Chapter Sections", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(ChapterSectionsToolResult)),
      Description("Get all sections and subsections in a specific chapter of the Essential C# book, in reading order. Returns each section's heading, slug, anchor link, and indent level. Use the returned slugs with other tools like GetSectionContent or GetNavigationContext.")]
     public ChapterSectionsToolResult GetChapterSections(
         [Description("The chapter number (e.g., 5 for Chapter 5).")] int chapter) =>
         _bookToolQueryService.GetChapterSections(chapter);
 
-    [McpServerTool(Title = "Get Direct Content URL", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true),
+    [McpServerTool(Title = "Get Direct Content URL", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false, UseStructuredContent = true, OutputSchemaType = typeof(BookSectionReferenceResult)),
      Description("Get the canonical deep-link URL and section metadata for a specific book section or subsection. Use this to include precise references in responses.")]
     public BookSectionReferenceResult GetDirectContentUrl(
         [Description("The section slug/key (e.g., 'hello-world'). Use GetChapterSections or GetChapterList to find valid slugs.")] string sectionKey) =>