Document mcp_publish_tool function signatures (closes #21)

- README: Show both overloads with named parameters, note all params
  are VARCHAR (not JSON type), add example with optional parameter
- Reference docs: Add VARCHAR warning admonition, document optional
  parameter NULL substitution behavior

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: teaguesterling

README.md

@@ -95,17 +95,36 @@ SELECT mcp_call_tool('server', 'analyze', '{"dataset": "sales"}');
 
 ## Publishing Custom Tools
 
+```sql
+-- 5-arg form (JSON output, the default)
+PRAGMA mcp_publish_tool(name, description, sql_template, properties_json, required_json);
+
+-- 6-arg form (explicit output format: 'json', 'markdown', or 'csv')
+PRAGMA mcp_publish_tool(name, description, sql_template, properties_json, required_json, format);
+```
+
+> **All parameters are VARCHAR.** Pass JSON as string literals, not `json_object(...)` or `JSON` type expressions.
+
+**Example:**
+
 ```sql
 PRAGMA mcp_publish_tool(
-    'search_products',
-    'Search products by name',
-    'SELECT * FROM products WHERE name ILIKE ''%'' || $query || ''%''',
-    '{"query": {"type": "string", "description": "Search term"}}',
-    '["query"]',
-    'markdown'
+    'search_products',                                                      -- name
+    'Search products by name with optional category filter',                -- description
+    'SELECT * FROM products
+     WHERE name ILIKE ''%'' || $query || ''%''
+       AND ($category IS NULL OR category = $category)',                    -- sql_template ($param placeholders)
+    '{
+        "query": {"type": "string", "description": "Search term"},
+        "category": {"type": "string", "description": "Category filter"}
+    }',                                                                     -- properties_json (JSON Schema)
+    '["query"]',                                                            -- required_json (category is optional)
+    'markdown'                                                              -- format
 );
 ```
 
+Optional parameters omitted by callers are substituted as SQL `NULL`. See the [Custom Tools Guide](https://duckdb-mcp.readthedocs.io/guides/custom-tools/) for full details.
+
 ## PRAGMA vs SELECT
 
 All server management and publishing functions are available in two forms:

docs/reference/server.md

@@ -270,12 +270,17 @@ SELECT mcp_publish_tool('name', 'description', 'sql_template', 'properties', 're
 | `required` | VARCHAR | JSON array of required parameter names |
 | `format` | VARCHAR | Output format: `json`, `csv`, `markdown` (default: `json`) |
 
+!!! warning "All parameters are VARCHAR"
+    Pass JSON as **string literals**, not `json_object(...)` or `JSON` type expressions. Using `json_object()` produces a `JSON` type which won't match the function signature.
+
 **Parameter Substitution:**
 
-Parameters in the SQL template use `$name` syntax:
+Parameters in the SQL template use `$name` syntax. Optional parameters (not listed in `required`) are substituted as SQL `NULL` when omitted or passed as JSON `null`:
 
 ```sql
-'SELECT * FROM products WHERE category = $category AND price < $max_price'
+'SELECT * FROM products
+ WHERE category = $category
+   AND ($max_price IS NULL OR price < $max_price)'
 ```
 
 **Examples:**