all: add examples of customizing tool schemas, and clarify documentation (#421)

Add example/server/toolschemas, which demonstrates various ways to
customize tool schemas, and illustrates the differences between
ToolHandler and ToolHandlerFor.

Fixes #385
Fixes #386
For #368

mcp/tool.go

@@ -14,14 +14,46 @@ import (
 )
 
 // A ToolHandler handles a call to tools/call.
-// This is a low-level API, for use with [Server.AddTool].
-// Most users will write a [ToolHandlerFor] and install it with [AddTool].
+//
+// This is a low-level API, for use with [Server.AddTool]. It does not do any
+// pre- or post-processing of the request or result: the params contain raw
+// arguments, no input validation is performed, and the result is returned to
+// the user as-is, without any validation of the output.
+//
+// Most users will write a [ToolHandlerFor] and install it with the generic
+// [AddTool] function.
+//
+// If ToolHandler returns an error, it is treated as a protocol error. By
+// contrast, [ToolHandlerFor] automatically populates [CallToolResult.IsError]
+// and [CallToolResult.Content] accordingly.
 type ToolHandler func(context.Context, *CallToolRequest) (*CallToolResult, error)
 
 // A ToolHandlerFor handles a call to tools/call with typed arguments and results.
+//
 // Use [AddTool] to add a ToolHandlerFor to a server.
-// Most users can ignore the [CallToolRequest] argument and [CallToolResult] return value.
-type ToolHandlerFor[In, Out any] func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)
+//
+// Unlike [ToolHandler], [ToolHandlerFor] provides significant functionality
+// out of the box, and enforces that the tool conforms to the MCP spec:
+//   - The In type provides a default input schema for the tool, though it may
+//     be overridden in [AddTool].
+//   - The input value is automatically unmarshaled from req.Params.Arguments.
+//   - The input value is automatically validated against its input schema.
+//     Invalid input is rejected before getting to the handler.
+//   - If the Out type is not the empty interface [any], it provides the
+//     default output schema for the tool (which again may be overridden in
+//     [AddTool]).
+//   - The Out value is used to populate result.StructuredOutput.
+//   - If [CallToolResult.Content] is unset, it is populated with the JSON
+//     content of the output.
+//   - An error result is treated as a tool error, rather than a protocol
+//     error, and is therefore packed into CallToolResult.Content, with
+//     [IsError] set.
+//
+// For these reasons, most users can ignore the [CallToolRequest] argument and
+// [CallToolResult] return values entirely. In fact, it is permissible to
+// return a nil CallToolResult, if you only care about returning a output value
+// or error. The effective result will be populated as described above.
+type ToolHandlerFor[In, Out any] func(_ context.Context, request *CallToolRequest, input In) (result *CallToolResult, output Out, _ error)
 
 // A serverTool is a tool definition that is bound to a tool handler.
 type serverTool struct {