diff --git a/.vscode/settings.json b/.vscode/settings.json
index c4ae9c7614..049330d2ae 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -25,6 +25,7 @@
   "[go]": {
     "editor.defaultFormatter": "golang.go"
   },
+  "java.autobuild.enabled": false,
   "java.configuration.updateBuildConfiguration": "automatic",
   "java.compile.nullAnalysis.mode": "automatic"
 }
diff --git a/java/pom.xml b/java/pom.xml
index 2b1cb3118e..5016a34b9d 100644
--- a/java/pom.xml
+++ b/java/pom.xml
@@ -76,6 +76,8 @@
             require npm or network access.
         -->
         <skip.cli.install>${skip.test.harness}</skip.cli.install>
+        <!-- Override with -Dnpm.loglevel=verbose when troubleshooting npm. -->
+        <npm.loglevel>notice</npm.loglevel>
         <!-- Extra JVM args for Surefire; overridden by the jdk21+ profile -->
         <surefire.jvm.args />
         <!--
@@ -213,6 +215,8 @@
                             <workingDirectory>${copilot.sdk.root}/test/harness</workingDirectory>
                             <arguments>
                                 <argument>ci</argument>
+                                <argument>--loglevel</argument>
+                                <argument>${npm.loglevel}</argument>
                             </arguments>
                         </configuration>
                     </execution>
@@ -235,6 +239,8 @@
                             <arguments>
                                 <argument>ci</argument>
                                 <argument>--ignore-scripts</argument>
+                                <argument>--loglevel</argument>
+                                <argument>${npm.loglevel}</argument>
                             </arguments>
                         </configuration>
                     </execution>
diff --git a/java/src/main/java/com/github/copilot/rpc/ParamSchema.java b/java/src/main/java/com/github/copilot/rpc/ParamSchema.java
index ee025eb2cc..bdb4f38ae1 100644
--- a/java/src/main/java/com/github/copilot/rpc/ParamSchema.java
+++ b/java/src/main/java/com/github/copilot/rpc/ParamSchema.java
@@ -14,6 +14,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.github.copilot.tool.Param;
 
@@ -84,7 +85,21 @@ static Map<String, Object> buildSchema(String toolName, ObjectMapper mapper, Par
         Map<String, Object> properties = new LinkedHashMap<>();
 
         for (Param<?> param : params) {
-            Map<String, Object> typeSchema = forType(param.type());
+            Map<String, Object> typeSchema;
+            if (!param.schema().isEmpty()) {
+                try {
+                    @SuppressWarnings("unchecked")
+                    Map<String, Object> parsed = mapper.readerFor(Map.class)
+                            .with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS)
+                            .with(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS).readValue(param.schema());
+                    typeSchema = parsed;
+                } catch (Exception e) {
+                    throw new IllegalArgumentException("Invalid schema JSON for parameter '" + param.name()
+                            + "' in tool '" + toolName + "': " + e.getMessage(), e);
+                }
+            } else {
+                typeSchema = forType(param.type());
+            }
             Map<String, Object> enriched = new LinkedHashMap<>(typeSchema);
             enriched.put("description", param.description());
             if (param.hasDefaultValue()) {
diff --git a/java/src/main/java/com/github/copilot/tool/CopilotToolParam.java b/java/src/main/java/com/github/copilot/tool/CopilotToolParam.java
index 0b667d9d71..144ea2e613 100644
--- a/java/src/main/java/com/github/copilot/tool/CopilotToolParam.java
+++ b/java/src/main/java/com/github/copilot/tool/CopilotToolParam.java
@@ -47,4 +47,22 @@
 
     /** Optional default value when the argument is omitted. */
     String defaultValue() default "";
+
+    /**
+     * Optional explicit JSON Schema for this parameter as a JSON string literal.
+     * When non-empty, bypasses automatic schema generation from the parameter type.
+     * The value must be a valid JSON object string.
+     *
+     * <p>
+     * Example:
+     *
+     * <pre>
+     * &#64;CopilotTool("Schedule meeting")
+     * public String schedule(
+     * 		&#64;CopilotToolParam(value = "When to meet", schema = "{\"type\":\"string\",\"format\":\"date-time\"}") MyCustomDateTime when) {
+     * 	// ...
+     * }
+     * </pre>
+     */
+    String schema() default "";
 }
diff --git a/java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java b/java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java
index 3ad6d8c0de..dbc6921afa 100644
--- a/java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java
+++ b/java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java
@@ -99,6 +99,20 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
                             "@CopilotToolParam(required=false) primitive parameters must provide defaultValue or use a boxed/Optional type",
                             param);
                 }
+                if (paramAnnotation != null && !paramAnnotation.schema().isEmpty()
+                        && !paramAnnotation.defaultValue().isEmpty()) {
+                    processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
+                            "@CopilotToolParam cannot have both schema and defaultValue — express defaults inside the schema if needed",
+                            param);
+                }
+                if (paramAnnotation != null && !paramAnnotation.schema().isEmpty()) {
+                    String schemaJson = paramAnnotation.schema().trim();
+                    if (!schemaJson.startsWith("{") || !schemaJson.endsWith("}")) {
+                        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
+                                "@CopilotToolParam schema must be a valid JSON object string (must start with '{' and end with '}')",
+                                param);
+                    }
+                }
             }
             if (toolInvocationParamCount > 1) {
                 processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
@@ -118,6 +132,11 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
                                     "@CopilotToolParam(defaultValue=...) is not supported on single-record tool parameters; use record component defaults or a non-record parameter",
                                     singleParam);
                         }
+                        if (!paramAnnotation.schema().isEmpty()) {
+                            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
+                                    "@CopilotToolParam(schema=...) is not supported on single-record tool parameters",
+                                    singleParam);
+                        }
                         if (!paramAnnotation.name().isEmpty() || !paramAnnotation.value().isEmpty()
                                 || !paramAnnotation.required()) {
                             processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
@@ -228,6 +247,21 @@ private void writeMetaClass(PrintWriter out, String packageName, String simpleCl
             out.println();
         }
 
+        if (needsJsonSourceHelpers(methods)) {
+            out.println("    private static Map<String, Object> mapOfNullable(Object... entries) {");
+            out.println("        var result = new LinkedHashMap<String, Object>();");
+            out.println("        for (int i = 0; i < entries.length; i += 2) {");
+            out.println("            result.put((String) entries[i], entries[i + 1]);");
+            out.println("        }");
+            out.println("        return Collections.unmodifiableMap(result);");
+            out.println("    }");
+            out.println();
+            out.println("    private static List<Object> listOfNullable(Object... items) {");
+            out.println("        return Collections.unmodifiableList(Arrays.asList(items));");
+            out.println("    }");
+            out.println();
+        }
+
         // definitions method
         out.println("    @Override");
         out.println("    @SuppressWarnings({\"unchecked\", \"rawtypes\"})");
@@ -263,6 +297,18 @@ private boolean needsWithMetaHelper(List<ExecutableElement> methods) {
         return false;
     }
 
+    private boolean needsJsonSourceHelpers(List<ExecutableElement> methods) {
+        for (ExecutableElement method : methods) {
+            for (VariableElement param : method.getParameters()) {
+                CopilotToolParam paramAnnotation = param.getAnnotation(CopilotToolParam.class);
+                if (paramAnnotation != null && !paramAnnotation.schema().isEmpty()) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
     private void writeToolDefinition(PrintWriter out, ExecutableElement method) {
         CopilotTool annotation = method.getAnnotation(CopilotTool.class);
         String toolName = annotation.name().isEmpty()
@@ -356,8 +402,19 @@ private String generateSchemaWithParamMetadata(List<? extends VariableElement> p
             CopilotToolParam paramAnnotation = param.getAnnotation(CopilotToolParam.class);
 
             // Generate the type schema for this parameter
-            String typeSchema = schemaGenerator.generateSchemaSource(paramType, processingEnv.getTypeUtils(),
-                    processingEnv.getElementUtils());
+            String typeSchema;
+            if (paramAnnotation != null && !paramAnnotation.schema().isEmpty()) {
+                try {
+                    typeSchema = jsonToMapOfSource(paramAnnotation.schema());
+                } catch (IllegalArgumentException e) {
+                    processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
+                            "@CopilotToolParam schema is not valid JSON: " + e.getMessage(), param);
+                    continue;
+                }
+            } else {
+                typeSchema = schemaGenerator.generateSchemaSource(paramType, processingEnv.getTypeUtils(),
+                        processingEnv.getElementUtils());
+            }
 
             // Build property schema with description and default if present
             String propertySchema = buildPropertySchema(typeSchema, paramAnnotation, paramType);
@@ -870,11 +927,289 @@ static String toSnakeCase(String name) {
         return sb.toString();
     }
 
+    // ------------------------------------------------------------------
+    // JSON-to-Java source code conversion
+    // ------------------------------------------------------------------
+
+    /**
+     * Converts a JSON object string to a Java source expression. Supports nested
+     * objects, arrays, strings, numbers, booleans, and null.
+     */
+    static String jsonToMapOfSource(String json) {
+        JsonToSourceConverter converter = new JsonToSourceConverter(json);
+        String result = converter.parseObject();
+        converter.skipWhitespace();
+        if (converter.pos < json.length()) {
+            throw new IllegalArgumentException("Unexpected trailing content at position " + converter.pos + ": '"
+                    + json.substring(converter.pos) + "'");
+        }
+        return result;
+    }
+
+    /**
+     * Minimal recursive-descent JSON parser that produces helper calls and literal
+     * Java source expressions from a JSON string. Only used at compile time by the
+     * annotation processor.
+     */
+    private static final class JsonToSourceConverter {
+
+        private final String input;
+        private int pos;
+
+        JsonToSourceConverter(String input) {
+            this.input = input;
+            this.pos = 0;
+        }
+
+        String parseObject() {
+            skipWhitespace();
+            expect('{');
+            skipWhitespace();
+            List<String> entries = new ArrayList<>();
+            if (peek() != '}') {
+                do {
+                    skipWhitespace();
+                    String key = parseString();
+                    skipWhitespace();
+                    expect(':');
+                    skipWhitespace();
+                    String value = parseValue();
+                    entries.add("\"" + escapeJava(key) + "\", " + value);
+                    skipWhitespace();
+                } while (tryConsume(','));
+            }
+            expect('}');
+            return "mapOfNullable(" + String.join(", ", entries) + ")";
+        }
+
+        private String parseArray() {
+            expect('[');
+            skipWhitespace();
+            List<String> items = new ArrayList<>();
+            if (peek() != ']') {
+                do {
+                    skipWhitespace();
+                    items.add(parseValue());
+                    skipWhitespace();
+                } while (tryConsume(','));
+            }
+            expect(']');
+            return "listOfNullable(" + String.join(", ", items) + ")";
+        }
+
+        private String parseValue() {
+            skipWhitespace();
+            char c = peek();
+            if (c == '{') {
+                return parseObject();
+            }
+            if (c == '[') {
+                return parseArray();
+            }
+            if (c == '"') {
+                return "\"" + escapeJava(parseString()) + "\"";
+            }
+            if (c == 't' || c == 'f') {
+                return parseBoolean();
+            }
+            if (c == 'n') {
+                return parseNull();
+            }
+            return parseNumber();
+        }
+
+        private String parseString() {
+            expect('"');
+            StringBuilder sb = new StringBuilder();
+            while (pos < input.length() && input.charAt(pos) != '"') {
+                char current = input.charAt(pos++);
+                if (current == '\\') {
+                    sb.append(parseEscape());
+                } else {
+                    if (current < 0x20) {
+                        throw new IllegalArgumentException("Unescaped control character at position " + (pos - 1));
+                    }
+                    sb.append(current);
+                }
+            }
+            expect('"');
+            return sb.toString();
+        }
+
+        private char parseEscape() {
+            if (pos >= input.length()) {
+                throw new IllegalArgumentException("Unterminated string escape at position " + pos);
+            }
+            char escaped = input.charAt(pos++);
+            return switch (escaped) {
+                case '"', '\\', '/' -> escaped;
+                case 'b' -> '\b';
+                case 'f' -> '\f';
+                case 'n' -> '\n';
+                case 'r' -> '\r';
+                case 't' -> '\t';
+                case 'u' -> parseUnicodeEscape();
+                default -> throw new IllegalArgumentException(
+                        "Invalid escape sequence \\" + escaped + " at position " + (pos - 2));
+            };
+        }
+
+        private char parseUnicodeEscape() {
+            if (pos + 4 > input.length()) {
+                throw new IllegalArgumentException("Incomplete Unicode escape at position " + (pos - 2));
+            }
+            int value = 0;
+            for (int i = 0; i < 4; i++) {
+                char hex = input.charAt(pos++);
+                if (!isAsciiHexDigit(hex)) {
+                    throw new IllegalArgumentException("Invalid Unicode escape at position " + (pos - 1));
+                }
+                int digit = Character.digit(hex, 16);
+                value = (value << 4) | digit;
+            }
+            return (char) value;
+        }
+
+        private boolean isAsciiHexDigit(char c) {
+            return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+        }
+
+        private String parseBoolean() {
+            if (input.startsWith("true", pos)) {
+                pos += 4;
+                return "true";
+            }
+            if (input.startsWith("false", pos)) {
+                pos += 5;
+                return "false";
+            }
+            throw new IllegalArgumentException("Expected boolean at position " + pos);
+        }
+
+        private String parseNull() {
+            if (input.startsWith("null", pos)) {
+                pos += 4;
+                return "(Object) null";
+            }
+            throw new IllegalArgumentException("Expected null at position " + pos);
+        }
+
+        private String parseNumber() {
+            int start = pos;
+            if (pos < input.length() && input.charAt(pos) == '-') {
+                pos++;
+            }
+            if (pos >= input.length()) {
+                throw new IllegalArgumentException("Expected number at position " + start);
+            }
+            if (input.charAt(pos) == '0') {
+                pos++;
+            } else if (isDigitOneToNine(input.charAt(pos))) {
+                consumeDigits();
+            } else {
+                throw new IllegalArgumentException("Expected number at position " + pos);
+            }
+            if (pos < input.length() && input.charAt(pos) == '.') {
+                pos++;
+                requireDigit("fraction");
+                consumeDigits();
+            }
+            if (pos < input.length() && (input.charAt(pos) == 'e' || input.charAt(pos) == 'E')) {
+                pos++;
+                if (pos < input.length() && (input.charAt(pos) == '+' || input.charAt(pos) == '-')) {
+                    pos++;
+                }
+                requireDigit("exponent");
+                consumeDigits();
+            }
+            String number = input.substring(start, pos);
+            try {
+                new java.math.BigDecimal(number);
+            } catch (NumberFormatException e) {
+                throw new IllegalArgumentException("Number cannot be represented at position " + start + ": " + number,
+                        e);
+            }
+            return "new java.math.BigDecimal(\"" + number + "\")";
+        }
+
+        private void requireDigit(String part) {
+            if (pos >= input.length() || !isAsciiDigit(input.charAt(pos))) {
+                throw new IllegalArgumentException("Expected digit in number " + part + " at position " + pos);
+            }
+        }
+
+        private void consumeDigits() {
+            while (pos < input.length() && isAsciiDigit(input.charAt(pos))) {
+                pos++;
+            }
+        }
+
+        private boolean isAsciiDigit(char c) {
+            return c >= '0' && c <= '9';
+        }
+
+        private boolean isDigitOneToNine(char c) {
+            return c >= '1' && c <= '9';
+        }
+
+        private void skipWhitespace() {
+            while (pos < input.length() && isJsonWhitespace(input.charAt(pos))) {
+                pos++;
+            }
+        }
+
+        private boolean isJsonWhitespace(char c) {
+            return c == ' ' || c == '\t' || c == '\r' || c == '\n';
+        }
+
+        private char peek() {
+            if (pos >= input.length()) {
+                throw new IllegalArgumentException("Unexpected end of JSON");
+            }
+            return input.charAt(pos);
+        }
+
+        private void expect(char c) {
+            if (pos >= input.length() || input.charAt(pos) != c) {
+                throw new IllegalArgumentException("Expected '" + c + "' at position " + pos + " but got '"
+                        + (pos < input.length() ? input.charAt(pos) : "EOF") + "'");
+            }
+            pos++;
+        }
+
+        private boolean tryConsume(char c) {
+            if (pos < input.length() && input.charAt(pos) == c) {
+                pos++;
+                return true;
+            }
+            return false;
+        }
+    }
+
     private static String escapeJava(String s) {
         if (s == null) {
             return "";
         }
-        return s.replace("\\", "\\\\").replace("\"", "\\\"").replace("\n", "\\n").replace("\r", "\\r").replace("\t",
-                "\\t");
+        StringBuilder escaped = new StringBuilder(s.length());
+        for (int i = 0; i < s.length(); i++) {
+            char current = s.charAt(i);
+            switch (current) {
+                case '\\' -> escaped.append("\\\\");
+                case '"' -> escaped.append("\\\"");
+                case '\b' -> escaped.append("\\b");
+                case '\f' -> escaped.append("\\f");
+                case '\n' -> escaped.append("\\n");
+                case '\r' -> escaped.append("\\r");
+                case '\t' -> escaped.append("\\t");
+                default -> {
+                    if (Character.isISOControl(current)) {
+                        escaped.append(String.format("\\%03o", (int) current));
+                    } else {
+                        escaped.append(current);
+                    }
+                }
+            }
+        }
+        return escaped.toString();
     }
 }
diff --git a/java/src/main/java/com/github/copilot/tool/Param.java b/java/src/main/java/com/github/copilot/tool/Param.java
index bbe188ce05..0060205f66 100644
--- a/java/src/main/java/com/github/copilot/tool/Param.java
+++ b/java/src/main/java/com/github/copilot/tool/Param.java
@@ -37,18 +37,33 @@ public final class Param<T> {
     private final String description;
     private final boolean required;
     private final String defaultValue;
+    private final String schema;
 
-    private Param(Class<T> type, String name, String description, boolean required, String defaultValue) {
+    private Param(Class<T> type, String name, String description, boolean required, String defaultValue,
+            String schema) {
         this.type = Objects.requireNonNull(type, "type");
         this.name = requireNonBlank(name, "name");
         this.description = requireNonBlank(description, "description");
         this.defaultValue = defaultValue == null ? "" : defaultValue;
+        this.schema = schema == null ? "" : schema;
         this.required = required;
 
         if (this.required && !this.defaultValue.isEmpty()) {
             throw new IllegalArgumentException("required=true cannot be combined with a non-empty defaultValue");
         }
 
+        if (!this.schema.isEmpty()) {
+            String trimmed = this.schema.trim();
+            if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+                throw new IllegalArgumentException(
+                        "schema must be a valid JSON object string (must start with '{' and end with '}')");
+            }
+            if (!this.defaultValue.isEmpty()) {
+                throw new IllegalArgumentException(
+                        "schema cannot be combined with defaultValue — express defaults inside the schema if needed");
+            }
+        }
+
         validateDefaultValue(type, this.defaultValue);
     }
 
@@ -70,7 +85,7 @@ private Param(Class<T> type, String name, String description, boolean required,
      *             if {@code name} or {@code description} is blank
      */
     public static <T> Param<T> of(Class<T> type, String name, String description) {
-        return new Param<>(type, name, description, true, "");
+        return new Param<>(type, name, description, true, "", "");
     }
 
     /**
@@ -96,7 +111,7 @@ public static <T> Param<T> of(Class<T> type, String name, String description) {
      */
     public static <T> Param<T> of(Class<T> type, String name, String description, boolean required,
             String defaultValue) {
-        return new Param<>(type, name, description, required, defaultValue);
+        return new Param<>(type, name, description, required, defaultValue, "");
     }
 
     /**
@@ -107,7 +122,7 @@ public static <T> Param<T> of(Class<T> type, String name, String description, bo
      * @return a new {@code Param} with the updated name
      */
     public Param<T> name(String name) {
-        return new Param<>(this.type, name, this.description, this.required, this.defaultValue);
+        return new Param<>(this.type, name, this.description, this.required, this.defaultValue, this.schema);
     }
 
     /**
@@ -118,7 +133,7 @@ public Param<T> name(String name) {
      * @return a new {@code Param} with the updated description
      */
     public Param<T> description(String description) {
-        return new Param<>(this.type, this.name, description, this.required, this.defaultValue);
+        return new Param<>(this.type, this.name, description, this.required, this.defaultValue, this.schema);
     }
 
     /**
@@ -129,7 +144,7 @@ public Param<T> description(String description) {
      * @return a new {@code Param} with the updated required flag
      */
     public Param<T> required(boolean required) {
-        return new Param<>(this.type, this.name, this.description, required, this.defaultValue);
+        return new Param<>(this.type, this.name, this.description, required, this.defaultValue, this.schema);
     }
 
     /**
@@ -142,7 +157,7 @@ public Param<T> required(boolean required) {
      *         false
      */
     public Param<T> defaultValue(String defaultValue) {
-        return new Param<>(this.type, this.name, this.description, false, defaultValue);
+        return new Param<>(this.type, this.name, this.description, false, defaultValue, this.schema);
     }
 
     /** Returns the Java type of this parameter. */
@@ -175,18 +190,37 @@ public boolean hasDefaultValue() {
         return !defaultValue.isEmpty();
     }
 
+    /**
+     * Returns a copy with an explicit JSON Schema override. When set, bypasses
+     * automatic schema generation from the parameter type.
+     *
+     * @param schema
+     *            a JSON object string (e.g.,
+     *            {@code "{\"type\":\"string\",\"format\":\"date-time\"}"} )
+     * @return a new {@code Param} with the schema override
+     */
+    public Param<T> schema(String schema) {
+        return new Param<>(this.type, this.name, this.description, this.required, this.defaultValue, schema);
+    }
+
+    /** Returns the explicit JSON Schema override, or empty if none. */
+    public String schema() {
+        return schema;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (!(o instanceof Param<?> other)) {
             return false;
         }
         return required == other.required && Objects.equals(type, other.type) && Objects.equals(name, other.name)
-                && Objects.equals(description, other.description) && Objects.equals(defaultValue, other.defaultValue);
+                && Objects.equals(description, other.description) && Objects.equals(defaultValue, other.defaultValue)
+                && Objects.equals(schema, other.schema);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(type, name, description, required, defaultValue);
+        return Objects.hash(type, name, description, required, defaultValue, schema);
     }
 
     @Override
diff --git a/java/src/test/java/com/github/copilot/rpc/ParamSchemaTest.java b/java/src/test/java/com/github/copilot/rpc/ParamSchemaTest.java
index 27d76a91a5..5aea4471da 100644
--- a/java/src/test/java/com/github/copilot/rpc/ParamSchemaTest.java
+++ b/java/src/test/java/com/github/copilot/rpc/ParamSchemaTest.java
@@ -5,10 +5,12 @@
 package com.github.copilot.rpc;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.math.BigDecimal;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
@@ -167,6 +169,89 @@ void buildSchema_multipleParams_orderPreservedInProperties() {
         assertEquals(List.of("alpha", "beta", "gamma"), keys);
     }
 
+    // ── buildSchema: schema override ───────────────────────────────────────────
+
+    @Test
+    void buildSchema_withSchemaOverride_usesExplicitSchema() {
+        Param<String> p = Param.of(String.class, "when", "Meeting time")
+                .schema("{\"type\":\"string\",\"format\":\"date-time\"}");
+        Map<String, Object> schema = ParamSchema.buildSchema("schedule", MAPPER, p);
+        @SuppressWarnings("unchecked")
+        Map<String, Object> props = (Map<String, Object>) schema.get("properties");
+        @SuppressWarnings("unchecked")
+        Map<String, Object> whenSchema = (Map<String, Object>) props.get("when");
+        assertEquals("string", whenSchema.get("type"));
+        assertEquals("date-time", whenSchema.get("format"));
+    }
+
+    @Test
+    void buildSchema_withSchemaOverride_preservesDescription() {
+        Param<String> p = Param.of(String.class, "when", "Meeting time")
+                .schema("{\"type\":\"string\",\"format\":\"date-time\"}");
+        Map<String, Object> schema = ParamSchema.buildSchema("schedule", MAPPER, p);
+        @SuppressWarnings("unchecked")
+        Map<String, Object> props = (Map<String, Object>) schema.get("properties");
+        @SuppressWarnings("unchecked")
+        Map<String, Object> whenSchema = (Map<String, Object>) props.get("when");
+        assertEquals("Meeting time", whenSchema.get("description"));
+    }
+
+    @Test
+    void buildSchema_withSchemaOverride_respectsRequired() {
+        Param<String> p = Param.of(String.class, "when", "Meeting time")
+                .schema("{\"type\":\"string\",\"format\":\"date-time\"}");
+        Map<String, Object> schema = ParamSchema.buildSchema("schedule", MAPPER, p);
+        @SuppressWarnings("unchecked")
+        List<String> required = (List<String>) schema.get("required");
+        assertTrue(required.contains("when"));
+    }
+
+    @Test
+    void buildSchema_mixedParams_overrideAndAuto() {
+        Param<String> pOverride = Param.of(String.class, "when", "Meeting time")
+                .schema("{\"type\":\"string\",\"format\":\"date-time\"}");
+        Param<String> pAuto = Param.of(String.class, "title", "Meeting title");
+        Map<String, Object> schema = ParamSchema.buildSchema("schedule", MAPPER, pOverride, pAuto);
+        @SuppressWarnings("unchecked")
+        Map<String, Object> props = (Map<String, Object>) schema.get("properties");
+
+        @SuppressWarnings("unchecked")
+        Map<String, Object> whenSchema = (Map<String, Object>) props.get("when");
+        assertEquals("date-time", whenSchema.get("format"));
+
+        @SuppressWarnings("unchecked")
+        Map<String, Object> titleSchema = (Map<String, Object>) props.get("title");
+        assertEquals("string", titleSchema.get("type"));
+        // Auto-generated should NOT have format
+        assertFalse(titleSchema.containsKey("format"));
+    }
+
+    @Test
+    void buildSchema_withSchemaOverride_rejectsTrailingJson() {
+        Param<String> param = Param.of(String.class, "when", "Meeting time")
+                .schema("{\"type\":\"string\"} {\"type\":\"integer\"}");
+
+        IllegalArgumentException error = assertThrows(IllegalArgumentException.class,
+                () -> ParamSchema.buildSchema("schedule", MAPPER, param));
+
+        assertTrue(error.getMessage().contains("Invalid schema JSON"));
+    }
+
+    @Test
+    void buildSchema_withSchemaOverride_preservesDecimalPrecision() {
+        Param<String> param = Param.of(String.class, "value", "Precise value")
+                .schema("{\"type\":\"number\",\"maximum\":1e400,\"multipleOf\":0.12345678901234567890}");
+
+        Map<String, Object> schema = ParamSchema.buildSchema("calculate", MAPPER, param);
+        @SuppressWarnings("unchecked")
+        Map<String, Object> properties = (Map<String, Object>) schema.get("properties");
+        @SuppressWarnings("unchecked")
+        Map<String, Object> valueSchema = (Map<String, Object>) properties.get("value");
+
+        assertEquals(new BigDecimal("1e400"), valueSchema.get("maximum"));
+        assertEquals(new BigDecimal("0.12345678901234567890"), valueSchema.get("multipleOf"));
+    }
+
     // ── forType: primitive and boxed integer types ───────────────────────────────
 
     @Test
diff --git a/java/src/test/java/com/github/copilot/rpc/ToolDefinitionLambdaTest.java b/java/src/test/java/com/github/copilot/rpc/ToolDefinitionLambdaTest.java
index 7f9ccaaba7..75752c67a4 100644
--- a/java/src/test/java/com/github/copilot/rpc/ToolDefinitionLambdaTest.java
+++ b/java/src/test/java/com/github/copilot/rpc/ToolDefinitionLambdaTest.java
@@ -48,6 +48,9 @@
 @AllowCopilotExperimental
 class ToolDefinitionLambdaTest {
 
+    private record CustomDateTime(String value) {
+    }
+
     // ── Helpers ──────────────────────────────────────────────────────────────────
 
     private static ToolInvocation invocationOf(Map<String, ?> args) {
@@ -485,6 +488,23 @@ void schema_oneArg_hasCorrectTypeForString() {
         assertEquals("Search query", querySchema.get("description"));
     }
 
+    @Test
+    void schema_oneArg_customTypeUsesExplicitSchemaAndCoercion() throws Exception {
+        Param<CustomDateTime> p = Param.of(CustomDateTime.class, "when", "Meeting time")
+                .schema("{\"type\":\"object\",\"properties\":{\"value\":{\"type\":\"string\"}}}");
+        ToolDefinition tool = ToolDefinition.from("schedule", "Schedules a meeting", p,
+                when -> "scheduled " + when.value());
+        @SuppressWarnings("unchecked")
+        Map<String, Object> whenSchema = (Map<String, Object>) propertiesOf(tool).get("when");
+        assertNotNull(whenSchema);
+        assertEquals("object", whenSchema.get("type"));
+        assertEquals("Meeting time", whenSchema.get("description"));
+        ObjectNode arguments = JsonNodeFactory.instance.objectNode();
+        arguments.putObject("when").put("value", "2026-07-23T21:00:00Z");
+        Object result = tool.handler().invoke(new ToolInvocation().setArguments(arguments)).get();
+        assertEquals("scheduled 2026-07-23T21:00:00Z", result);
+    }
+
     @Test
     void schema_oneArg_hasCorrectTypeForInteger() {
         Param<Integer> p = Param.of(Integer.class, "count", "Item count");
diff --git a/java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java b/java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java
index 71e026c399..f0623d92ed 100644
--- a/java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java
+++ b/java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java
@@ -7,6 +7,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.io.File;
@@ -14,6 +15,7 @@
 import java.io.IOException;
 import java.io.Writer;
 import java.net.URI;
+import java.net.URLClassLoader;
 import java.nio.file.Path;
 import java.security.CodeSource;
 import java.util.ArrayList;
@@ -38,6 +40,9 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
+import com.github.copilot.rpc.ToolDefinition;
+import com.github.copilot.rpc.ToolInvocation;
+
 /**
  * Tests that {@link CopilotToolProcessor} correctly generates
  * {@code $$CopilotToolMeta} companion classes and emits compile errors for
@@ -168,6 +173,30 @@ public String search(@CopilotToolParam(defaultValue = "fallback") SearchArgs req
                 "Expected compile error for single-record wrapper defaultValue, got: " + result.diagnostics);
     }
 
+    @Test
+    void emitsError_forSingleRecordWrapperSchemaWithoutUnsupportedGuidance() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class SingleRecordSchemaTools {
+                    public record SearchArgs(String query, int limit) {}
+                    @CopilotTool("Single record")
+                    public String search(@CopilotToolParam(schema = "{\\"type\\":\\"object\\"}") SearchArgs req) {
+                    return req.query();
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(
+                List.of(inMemorySource("test.SingleRecordSchemaTools", source)));
+
+        assertTrue(hasErrorContaining(result, "schema=...) is not supported on single-record tool parameters"),
+                "Expected unsupported schema diagnostic, got: " + result.diagnostics);
+        assertFalse(hasErrorContaining(result, "annotate record components"),
+                "Diagnostic must not recommend unsupported record-component annotations: " + result.diagnostics);
+    }
+
     @Test
     void emitsError_forSingleRecordWrapperMetadataOverrides() {
         String source = """
@@ -189,6 +218,235 @@ public String search(@CopilotToolParam(value = "Search input", required = false,
                 "Expected compile error for single-record wrapper metadata overrides, got: " + result.diagnostics);
     }
 
+    // ── Test: @CopilotToolParam schema override ─────────────────────────────────
+
+    @Test
+    void generatesCorrectSchema_forExplicitSchemaOverride() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class SchemaOverrideTools {
+                    @CopilotTool("Schedule meeting")
+                    public String schedule(
+                            @CopilotToolParam(value = "When to meet",
+                                schema = "{\\"type\\":\\"string\\",\\"format\\":\\"date-time\\"}") String when) {
+                        return "scheduled " + when;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.SchemaOverrideTools", source)));
+
+        assertNoErrors(result);
+        assertTrue(result.generatedSources.stream().anyMatch(s -> s.contains("date-time")),
+                "Expected generated code to contain the custom schema format, got: " + result.generatedSources);
+    }
+
+    @Test
+    void generatedSchemaOverride_supportsCustomTypeHandlerInvocation() throws Exception {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class AnnotationSchemaTools {
+                    public static class CustomDateTime {
+                        public String value;
+                    }
+                    @CopilotTool("Schedule meeting")
+                    public String schedule(@CopilotToolParam(value = "Meeting time",
+                        schema = "{\\"type\\":\\"object\\",\\"properties\\":{\\"value\\":{\\"type\\":\\"string\\"}}}") CustomDateTime when) {
+                        return "scheduled " + when.value;
+                    }
+                }
+                """;
+
+        CompilationResult compilation = compileWithProcessor(
+                List.of(inMemorySource("test.AnnotationSchemaTools", source)));
+        assertNoErrors(compilation);
+
+        try (URLClassLoader loader = new URLClassLoader(new java.net.URL[]{compilation.outputDir.toUri().toURL()},
+                getClass().getClassLoader())) {
+            Class<?> toolsClass = loader.loadClass("test.AnnotationSchemaTools");
+            Object tools = toolsClass.getConstructor().newInstance();
+            Class<?> providerClass = loader.loadClass("test.AnnotationSchemaTools$$CopilotToolMeta");
+            @SuppressWarnings("unchecked")
+            CopilotToolMetadataProvider<Object> provider = (CopilotToolMetadataProvider<Object>) providerClass
+                    .getConstructor().newInstance();
+            ToolDefinition tool = provider.definitions(tools, new com.fasterxml.jackson.databind.ObjectMapper()).get(0);
+
+            @SuppressWarnings("unchecked")
+            Map<String, Object> schema = (Map<String, Object>) tool.parameters();
+            @SuppressWarnings("unchecked")
+            Map<String, Object> properties = (Map<String, Object>) schema.get("properties");
+            @SuppressWarnings("unchecked")
+            Map<String, Object> whenSchema = (Map<String, Object>) properties.get("when");
+            assertEquals("object", whenSchema.get("type"));
+
+            var arguments = com.fasterxml.jackson.databind.node.JsonNodeFactory.instance.objectNode();
+            arguments.putObject("when").put("value", "2026-07-23T22:00:00Z");
+            Object result = tool.handler().invoke(new ToolInvocation().setArguments(arguments)).get();
+            assertEquals("scheduled 2026-07-23T22:00:00Z", result);
+        }
+    }
+
+    @Test
+    void emitsError_forSchemaWithDefaultValue() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class SchemaDefaultConflict {
+                    @CopilotTool("Do something")
+                    public String doIt(
+                            @CopilotToolParam(value = "Input",
+                                schema = "{\\"type\\":\\"string\\"}",
+                                defaultValue = "hello") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.SchemaDefaultConflict", source)));
+
+        assertTrue(hasErrorContaining(result, "schema and defaultValue"),
+                "Expected compile error for schema + defaultValue conflict, got: " + result.diagnostics);
+    }
+
+    @Test
+    void emitsError_forInvalidSchemaJson() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class InvalidSchemaTools {
+                    @CopilotTool("Do something")
+                    public String doIt(
+                            @CopilotToolParam(value = "Input", schema = "not json") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.InvalidSchemaTools", source)));
+
+        assertTrue(hasErrorContaining(result, "valid JSON object string"),
+                "Expected compile error for invalid schema JSON, got: " + result.diagnostics);
+    }
+
+    @Test
+    void emitsError_forUnrepresentableSchemaNumber() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class UnrepresentableSchemaNumberTools {
+                    @CopilotTool("Do something")
+                    public String doIt(
+                            @CopilotToolParam(value = "Input", schema = "{\\"maximum\\":1e9999999999}") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(
+                List.of(inMemorySource("test.UnrepresentableSchemaNumberTools", source)));
+
+        assertTrue(hasErrorContaining(result, "Number cannot be represented"),
+                "Expected compile error for unrepresentable schema number, got: " + result.diagnostics);
+    }
+
+    @Test
+    void compilesSuccessfully_forEmptySchemaFallsThrough() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class EmptySchemaTools {
+                    @CopilotTool("Search")
+                    public String search(@CopilotToolParam(value = "Query", schema = "") String query) {
+                        return query;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.EmptySchemaTools", source)));
+
+        assertNoErrors(result);
+    }
+
+    @Test
+    void generatesSchemaOverride_withLargeObjectsNullAndNumbers() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class ComplexSchemaTools {
+                    @CopilotTool("Complex schema")
+                    public String useSchema(@CopilotToolParam(value = "Input",
+                        schema = "{\\"type\\":\\"object\\",\\"const\\":null,\\"enum\\":[\\"x\\",null],\\"minimum\\":2147483648,\\"k1\\":true,\\"k2\\":true,\\"k3\\":true,\\"k4\\":true,\\"k5\\":true,\\"k6\\":true,\\"k7\\":true}") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.ComplexSchemaTools", source)));
+
+        assertNoErrors(result);
+        String generated = result.getGeneratedSource("test.ComplexSchemaTools$$CopilotToolMeta");
+        assertTrue(generated.contains("mapOfNullable("), "Expected arity-independent map helper, got:\n" + generated);
+        assertTrue(generated.contains("new java.math.BigDecimal(\"2147483648\")"),
+                "Expected safe numeric source, got:\n" + generated);
+        assertTrue(generated.contains("\"const\", (Object) null"), "Expected null schema value, got:\n" + generated);
+        assertTrue(generated.contains("listOfNullable(\"x\", (Object) null)"),
+                "Expected null-tolerant list helper, got:\n" + generated);
+    }
+
+    @Test
+    void jsonToMapOfSource_decodesEscapesAndRejectsMalformedJson() {
+        String generated = CopilotToolProcessor.jsonToMapOfSource("{\"title\":\"line\\n\\u0061\"}");
+
+        assertTrue(generated.contains("\"title\", \"line\\na\""), "Expected decoded JSON escapes, got: " + generated);
+        IllegalArgumentException escapeError = assertThrows(IllegalArgumentException.class,
+                () -> CopilotToolProcessor.jsonToMapOfSource("{\"title\":\"\\q\"}"));
+        assertTrue(escapeError.getMessage().contains("Invalid escape sequence"));
+        IllegalArgumentException numberError = assertThrows(IllegalArgumentException.class,
+                () -> CopilotToolProcessor.jsonToMapOfSource("{\"minimum\":1.}"));
+        assertTrue(numberError.getMessage().contains("Expected digit in number fraction"));
+        assertThrows(IllegalArgumentException.class,
+                () -> CopilotToolProcessor.jsonToMapOfSource("{\"minimum\":1\u0662}"));
+        assertThrows(IllegalArgumentException.class,
+                () -> CopilotToolProcessor.jsonToMapOfSource("{\f\"type\":\"string\"}"));
+        assertEquals("mapOfNullable(\"enum\", listOfNullable((Object) null))",
+                CopilotToolProcessor.jsonToMapOfSource("{\"enum\":[null]}"));
+        assertThrows(IllegalArgumentException.class,
+                () -> CopilotToolProcessor.jsonToMapOfSource("{\"title\":\"\\" + "u١٢٣٤\"}"));
+    }
+
+    @Test
+    void generatesSchemaOverride_withEscapedControlCharacters() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class EscapedControlSchemaTools {
+                    @CopilotTool("Escaped control schema")
+                    public String useSchema(@CopilotToolParam(value = "Input",
+                        schema = "{\\"title\\":\\"\\\\b\\\\fUNICODE_ESCAPE\\"}") String input) {
+                        return input;
+                    }
+                }
+                """.replace("UNICODE_ESCAPE", "\\\\" + "u0000");
+
+        CompilationResult result = compileWithProcessor(
+                List.of(inMemorySource("test.EscapedControlSchemaTools", source)));
+
+        assertNoErrors(result);
+        String generated = result.getGeneratedSource("test.EscapedControlSchemaTools$$CopilotToolMeta");
+        assertTrue(generated.contains("\\b\\f\\000"),
+                "Expected Java-safe control escapes in generated source, got:\n" + generated);
+    }
+
     // ── Test: Blank @CopilotToolParam description validation ────────────────────
 
     @Test
@@ -361,7 +619,8 @@ public String doSomething(@CopilotToolParam("Input") String input) {
         String generated = result.getGeneratedSource("test.PlainTools$$CopilotToolMeta");
         assertFalse(generated.contains("Map.<String, Object>of("),
                 "Expected no metadata map for a tool without metadata, got:\n" + generated);
-        assertTrue(generated.contains("                null\n            )"),
+        String normalizedGenerated = generated.replace("\r\n", "\n").replace('\r', '\n');
+        assertTrue(normalizedGenerated.contains("                null\n            )"),
                 "Expected metadata constructor argument to be null when metadata is absent, got:\n" + generated);
     }
 
diff --git a/java/src/test/java/com/github/copilot/tool/ParamTest.java b/java/src/test/java/com/github/copilot/tool/ParamTest.java
index 75f6e44222..c2b38a4cee 100644
--- a/java/src/test/java/com/github/copilot/tool/ParamTest.java
+++ b/java/src/test/java/com/github/copilot/tool/ParamTest.java
@@ -243,6 +243,52 @@ void toStringContainsName() {
         assertTrue(p.toString().contains("String"));
     }
 
+    // ------------------------------------------------------------------
+    // Schema override validation
+    // ------------------------------------------------------------------
+
+    @Test
+    void rejectsSchemaWithDefaultValue() {
+        var ex = assertThrows(IllegalArgumentException.class,
+                () -> Param.of(String.class, "x", "desc").schema("{\"type\":\"string\"}").defaultValue("hello"));
+        assertTrue(ex.getMessage().contains("schema"));
+        assertTrue(ex.getMessage().contains("defaultValue"));
+    }
+
+    @Test
+    void rejectsSchemaNotStartingWithBrace() {
+        var ex = assertThrows(IllegalArgumentException.class,
+                () -> Param.of(String.class, "x", "desc").schema("not json"));
+        assertTrue(ex.getMessage().contains("schema"));
+    }
+
+    @Test
+    void rejectsSchemaNotEndingWithBrace() {
+        var ex = assertThrows(IllegalArgumentException.class,
+                () -> Param.of(String.class, "x", "desc").schema("{\"type\":\"string\""));
+        assertTrue(ex.getMessage().contains("schema"));
+    }
+
+    @Test
+    void acceptsValidSchemaJson() {
+        Param<String> p = Param.of(String.class, "x", "desc").schema("{\"type\":\"string\",\"format\":\"date-time\"}");
+        assertEquals("{\"type\":\"string\",\"format\":\"date-time\"}", p.schema());
+    }
+
+    @Test
+    void acceptsEmptySchema() {
+        Param<String> p = Param.of(String.class, "x", "desc");
+        assertEquals("", p.schema());
+    }
+
+    @Test
+    void schemaPreservedAcrossFluentCopies() {
+        Param<String> base = Param.of(String.class, "x", "desc").schema("{\"type\":\"string\"}");
+        assertEquals("{\"type\":\"string\"}", base.name("y").schema());
+        assertEquals("{\"type\":\"string\"}", base.description("other").schema());
+        assertEquals("{\"type\":\"string\"}", base.required(false).schema());
+    }
+
     // ------------------------------------------------------------------
     // Null type rejected
     // ------------------------------------------------------------------