feat(tool): add additionalProperties support to @tool annotation

Add additionalProperties parameter to @tool annotation to control
whether LLM can pass extra parameters not defined in the schema.
When set to false, ToolValidator rejects hallucinated params.

Closes #1379

Author: itxaiohanglover

agentscope-core/src/main/java/io/agentscope/core/tool/Tool.java

@@ -130,4 +130,18 @@
      * @see DefaultToolResultConverter
      */
     Class<? extends ToolResultConverter> converter() default DefaultToolResultConverter.class;
+
+    /**
+     * Whether to allow additional properties beyond those defined in the schema.
+     *
+     * <p>Corresponds to the {@code additionalProperties} keyword in JSON Schema. When set to
+     * {@code false}, any extra parameters passed by the LLM that are not defined in the schema will
+     * cause a validation error, preventing the LLM from hallucinating undefined parameters.
+     *
+     * <p>This setting is applied recursively to all nested objects within the generated schema.
+     *
+     * @return {@code true} to allow additional properties (default, backward compatible), {@code
+     *     false} to disallow
+     */
+    boolean additionalProperties() default true;
 }

agentscope-core/src/main/java/io/agentscope/core/tool/ToolSchemaGenerator.java

@@ -33,6 +33,77 @@
  */
 class ToolSchemaGenerator {
 
+    /**
+     * Generate parameter schema with additionalProperties control.
+     *
+     * @param method the method to generate schema for
+     * @param excludeParams set of parameter names to exclude (may be null or empty)
+     * @param allowAdditionalProperties whether to allow additional properties in the schema
+     * @return JSON Schema map
+     */
+    @SuppressWarnings("unchecked")
+    Map<String, Object> generateParameterSchema(
+            Method method, Set<String> excludeParams, boolean allowAdditionalProperties) {
+        Map<String, Object> schema = generateParameterSchema(method, excludeParams);
+
+        if (!allowAdditionalProperties) {
+            addAdditionalPropertiesFalseRecursively(schema);
+        }
+
+        return schema;
+    }
+
+    @SuppressWarnings("unchecked")
+    private void addAdditionalPropertiesFalseRecursively(Map<String, Object> schema) {
+        if (!"object".equals(schema.get("type"))) {
+            return;
+        }
+        // Skip if user already set additionalProperties explicitly
+        if (schema.containsKey("additionalProperties")) {
+            return;
+        }
+        schema.put("additionalProperties", false);
+
+        Object propsObj = schema.get("properties");
+        if (propsObj instanceof Map) {
+            Map<String, Object> props = (Map<String, Object>) propsObj;
+            for (Map.Entry<String, Object> entry : props.entrySet()) {
+                if (entry.getValue() instanceof Map) {
+                    addAdditionalPropertiesFalseRecursively((Map<String, Object>) entry.getValue());
+                }
+            }
+        }
+
+        Object itemsObj = schema.get("items");
+        if (itemsObj instanceof Map) {
+            addAdditionalPropertiesFalseRecursively((Map<String, Object>) itemsObj);
+        }
+
+        for (String key : new String[] {"oneOf", "anyOf", "allOf"}) {
+            Object listObj = schema.get(key);
+            if (listObj instanceof Iterable) {
+                for (Object item : (Iterable<?>) listObj) {
+                    if (item instanceof Map) {
+                        addAdditionalPropertiesFalseRecursively((Map<String, Object>) item);
+                    }
+                }
+            }
+        }
+
+        for (String defsKey : new String[] {"$defs", "definitions"}) {
+            Object defsObj = schema.get(defsKey);
+            if (defsObj instanceof Map) {
+                Map<String, Object> defs = (Map<String, Object>) defsObj;
+                for (Map.Entry<String, Object> entry : defs.entrySet()) {
+                    if (entry.getValue() instanceof Map) {
+                        addAdditionalPropertiesFalseRecursively(
+                                (Map<String, Object>) entry.getValue());
+                    }
+                }
+            }
+        }
+    }
+
     /**
      * Generate parameter schema for a method with excluded parameters.
      *

agentscope-core/src/main/java/io/agentscope/core/tool/Toolkit.java

@@ -373,7 +373,8 @@ public Map<String, Object> getParameters() {
                                 presetParameters != null
                                         ? presetParameters.keySet()
                                         : Collections.emptySet();
-                        return schemaGenerator.generateParameterSchema(method, excludeParams);
+                        return schemaGenerator.generateParameterSchema(
+                                method, excludeParams, toolAnnotation.additionalProperties());
                     }
 
                     @Override