From a16cb5323d40d0b292c547c8a7f0511077e57e0a Mon Sep 17 00:00:00 2001
From: Elias Bachaalany <elias.bachaalany@gmail.com>
Date: Fri, 30 Jan 2026 14:00:03 -0800
Subject: [PATCH] docs: use fluent tool builder syntax in README

Replace verbose JSON schema construction with cleaner fluent API:
- ToolBuilder with .param<T>() for type-safe parameters
- make_tool() for quick one-liners
- Auto-generated JSON schemas from C++ types

Also add tests/.gitignore for byok.env (API keys)
---
 README.md        | 79 ++++++++++++++++++++++--------------------------
 tests/.gitignore |  1 +
 2 files changed, 37 insertions(+), 43 deletions(-)
 create mode 100644 tests/.gitignore

diff --git a/README.md b/README.md
index 9fa10cd..2ccd29e 100644
--- a/README.md
+++ b/README.md
@@ -35,74 +35,67 @@ Snapshot conformance tests (optional):
 
 ## Custom Tools
 
-Custom tools must be provided when creating or resuming a session. The SDK registers tool handlers locally and sends tool definitions to the server:
+Custom tools are provided when creating or resuming a session. The SDK auto-generates JSON schemas from C++ types.
+
+### Fluent Builder (Recommended)
 
 ```cpp
-// Define your tool
-copilot::Tool calc_tool;
-calc_tool.name = "calculator";
-calc_tool.description = "Perform math calculations";
-calc_tool.parameters_schema = copilot::json{
-    {"type", "object"},
-    {"properties", {{"expression", {{"type", "string"}}}}},
-    {"required", {"expression"}}
-};
-calc_tool.handler = [](const copilot::ToolInvocation& inv) {
-    copilot::ToolResultObject result;
-    // Handle the tool call...
-    return result;
-};
-
-// Pass tools when creating the session
+#include <copilot/tool_builder.hpp>
+
+// Fluent builder with full control over parameters
+auto calc = copilot::ToolBuilder("calculator", "Perform math calculations")
+    .param<std::string>("expression", "Math expression to evaluate")
+    .handler([](std::string expression) {
+        // Evaluate expression...
+        return "42";
+    });
+
+// With enum constraints and default values
+auto search = copilot::ToolBuilder("search", "Search the web")
+    .param<std::string>("query", "Search query")
+    .param<int>("limit", "Max results").default_value(10)
+    .param<std::string>("sort", "Sort order").one_of("relevance", "date")
+    .handler([](std::string query, int limit, std::string sort) {
+        return "Results for: " + query;
+    });
+
+// Use in session
 copilot::SessionConfig config;
-config.tools = {calc_tool};
+config.tools = {calc, search};
 auto session = client.create_session(config).get();
-
-// Or when resuming an existing session
-copilot::ResumeSessionConfig resume_config;
-resume_config.tools = {calc_tool};
-auto session = client.resume_session(session_id, resume_config).get();
 ```
 
-See `examples/tools.cpp` and `examples/resume_with_tools.cpp` for complete examples.
-
-### Fluent Tool Builder
-
-Use `make_tool` to create tools with automatic schema generation from lambda signatures:
+### Quick One-Liner with `make_tool`
 
 ```cpp
-#include <copilot/tool_builder.hpp>
-
-// Single parameter - schema auto-generated
-auto echo_tool = copilot::make_tool(
+// Simple tools with auto-generated schema
+auto echo = copilot::make_tool(
     "echo", "Echo a message",
     [](std::string message) { return message; },
-    {"message"}  // Parameter names
+    {"message"}
 );
 
-// Multiple parameters
-auto calc_tool = copilot::make_tool(
+auto add = copilot::make_tool(
     "add", "Add two numbers",
     [](double a, double b) { return std::to_string(a + b); },
     {"first", "second"}
 );
 
-// Optional parameters (not added to "required" in schema)
-auto greet_tool = copilot::make_tool(
+// Optional parameters (use std::optional)
+auto greet = copilot::make_tool(
     "greet", "Greet someone",
     [](std::string name, std::optional<std::string> title) {
-        if (title)
-            return "Hello, " + *title + " " + name + "!";
-        return "Hello, " + name + "!";
+        return title ? "Hello, " + *title + " " + name + "!"
+                     : "Hello, " + name + "!";
     },
     {"name", "title"}
 );
 
-// Use in session config
-copilot::SessionConfig config;
-config.tools = {echo_tool, calc_tool, greet_tool};
+config.tools = {echo, add, greet};
 ```
 
+See `examples/tools.cpp` and `examples/resume_with_tools.cpp` for complete examples.
+
 ## BYOK (Bring Your Own Key)
 
 Use your own API key instead of GitHub Copilot authentication.
diff --git a/tests/.gitignore b/tests/.gitignore
new file mode 100644
index 0000000..b6c26dc
--- /dev/null
+++ b/tests/.gitignore
@@ -0,0 +1 @@
+byok.env
\ No newline at end of file