docs: document tool support (#498)

Document tool support, and tweak the wording for prompts.

For #442

mcp/client.go

@@ -571,8 +571,9 @@ func (cs *ClientSession) ListTools(ctx context.Context, params *ListToolsParams)
 	return handleSend[*ListToolsResult](ctx, methodListTools, newClientRequest(cs, orZero[Params](params)))
 }
 
-// CallTool calls the tool with the given name and arguments.
-// The arguments can be any value that marshals into a JSON object.
+// CallTool calls the tool with the given parameters.
+//
+// The params.Arguments can be any value that marshals into a JSON object.
 func (cs *ClientSession) CallTool(ctx context.Context, params *CallToolParams) (*CallToolResult, error) {
 	if params == nil {
 		params = new(CallToolParams)

mcp/protocol.go

@@ -42,11 +42,14 @@ type Annotations struct {
 
 // CallToolParams is used by clients to call a tool.
 type CallToolParams struct {
-	// This property is reserved by the protocol to allow clients and servers to
+	// Meta is reserved by the protocol to allow clients and servers to
 	// attach additional metadata to their responses.
-	Meta      `json:"_meta,omitempty"`
-	Name      string `json:"name"`
-	Arguments any    `json:"arguments,omitempty"`
+	Meta `json:"_meta,omitempty"`
+	// Name is the name of the tool to call.
+	Name string `json:"name"`
+	// Arguments holds the tool arguments. It can hold any value that can be
+	// marshaled to JSON.
+	Arguments any `json:"arguments,omitempty"`
 }
 
 // CallToolParamsRaw is passed to tool handlers on the server. Its arguments
@@ -55,8 +58,12 @@ type CallToolParams struct {
 type CallToolParamsRaw struct {
 	// This property is reserved by the protocol to allow clients and servers to
 	// attach additional metadata to their responses.
-	Meta      `json:"_meta,omitempty"`
-	Name      string          `json:"name"`
+	Meta `json:"_meta,omitempty"`
+	// Name is the name of the tool being called.
+	Name string `json:"name"`
+	// Arguments is the raw arguments received over the wire from the client. It
+	// is the responsibility of the tool handler to unmarshal and validate the
+	// Arguments (see [AddTool]).
 	Arguments json.RawMessage `json:"arguments,omitempty"`
 }
 

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 {