docs: document tool support (#498)

Document tool support, and tweak the wording for prompts.

For #442

mcp/tool_example_test.go

@@ -83,11 +83,6 @@ func ExampleAddTool_customMarshalling() {
 	// }
 }
 
-type WeatherInput struct {
-	Location Location `json:"location" jsonschema:"user location"`
-	Days     int      `json:"days" jsonschema:"number of days to forecast"`
-}
-
 type Location struct {
 	Name      string   `json:"name"`
 	Latitude  *float64 `json:"latitude,omitempty"`
@@ -114,6 +109,13 @@ const (
 
 type Probability float64
 
+// !+weathertool
+
+type WeatherInput struct {
+	Location Location `json:"location" jsonschema:"user location"`
+	Days     int      `json:"days" jsonschema:"number of days to forecast"`
+}
+
 type WeatherOutput struct {
 	Summary       string      `json:"summary" jsonschema:"a summary of the weather forecast"`
 	Confidence    Probability `json:"confidence" jsonschema:"confidence, between 0 and 1"`
@@ -140,11 +142,15 @@ func WeatherTool(ctx context.Context, req *mcp.CallToolRequest, in WeatherInput)
 	return nil, perfectWeather, nil
 }
 
+// !-weathertool
+
 func ExampleAddTool_complexSchema() {
 	// This example demonstrates a tool with a more 'realistic' input and output
 	// schema. We use a combination of techniques to tune our input and output
 	// schemas.
 
+	// !+customschemas
+
 	// Distinguished Go types allow custom schemas to be reused during inference.
 	customSchemas := map[any]*jsonschema.Schema{
 		Probability(0):  {Type: "number", Minimum: jsonschema.Ptr(0.0), Maximum: jsonschema.Ptr(1.0)},
@@ -177,6 +183,8 @@ func ExampleAddTool_complexSchema() {
 		OutputSchema: out,
 	}, WeatherTool)
 
+	// !-customschemas
+
 	ctx := context.Background()
 	session, err := connect(ctx, server) // create an in-memory connection
 	if err != nil {