Add schema notes for avoiding propertyNames

Author: Tarquinen

SCHEMA_NOTES.md

@@ -0,0 +1,63 @@
+# Tool Schema Notes
+
+## Avoiding `propertyNames` in JSON Schema
+
+### Problem
+
+When defining tool arguments that accept arbitrary object maps (e.g., `Record<string, object>`), using `z.record()` generates a `propertyNames` constraint in the JSON Schema:
+
+```typescript
+// This generates propertyNames
+distillation: tool.schema.record(tool.schema.string(), tool.schema.any())
+```
+
+Produces:
+
+```json
+{
+    "type": "object",
+    "propertyNames": { "type": "string" },
+    "additionalProperties": {}
+}
+```
+
+The `propertyNames` keyword is not supported by some LLM APIs (Claude, Gemini via Antigravity), causing tool schema validation failures.
+
+### Solution
+
+Use `z.object({}).catchall()` instead of `z.record()`:
+
+```typescript
+// This does NOT generate propertyNames
+distillation: tool.schema.object({}).catchall(tool.schema.object({}).loose())
+```
+
+Produces:
+
+```json
+{
+    "type": "object",
+    "properties": {},
+    "additionalProperties": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": {}
+    }
+}
+```
+
+### Pattern Reference
+
+| Use Case                         | Syntax                                              |
+| -------------------------------- | --------------------------------------------------- |
+| Any keys, any values             | `z.object({}).loose()`                              |
+| Any keys, object values (loose)  | `z.object({}).catchall(z.object({}).loose())`       |
+| Any keys, object values (strict) | `z.object({}).catchall(z.object({ ... }))`          |
+| Known keys + unknown extras      | `z.object({ known: z.string() }).catchall(z.any())` |
+
+### Notes
+
+- `z.record()` always adds `propertyNames` - avoid it for API compatibility
+- `.loose()` and `.passthrough()` produce identical JSON Schema output
+- `.catchall(valueSchema)` constrains the value type without adding `propertyNames`
+- JSON keys are inherently strings, so `propertyNames: { type: "string" }` is redundant anyway