feat: add Tool.Title, OpenWorldHint=true, and OutputSchema for all tools (#45)

Closes #44

## Changes

### Tool.Title
- Add `pkg/tools/titles.go` with default human-readable titles for all 9
  tools and a three-level priority chain (default → toolkit → per-registration)
- Add `WithTitles(map[ToolName]string)` toolkit-level option
- Add `WithTitle(string)` per-registration ToolOption
- Wire `Title` field in all 9 tool registration calls

### OpenWorldHint
- Change `OpenWorldHint` from `false` to `true` for all 9 tools; S3 tools
  interact with external object storage and are open-world by definition
- Update annotations_test.go to assert `true`

### OutputSchema
- Add `pkg/tools/output_schemas.go` with JSON Schema 2020-12 objects for
  all 9 tools, matching actual response struct fields in types.go
- Schemas declare `type` + `properties` only (no `required` / no
  `additionalProperties: false`) to avoid runtime validation failures on
  optional or implementation-specific fields
- Add `WithOutputSchemas(map[ToolName]any)` toolkit-level option
- Add `WithOutputSchema(any)` per-registration ToolOption
- Wire `OutputSchema` field in all 9 tool registration calls

### toolConfig / Toolkit structs
- Add `title *string` and `outputSchema any` to `toolConfig`
- Add `titles map[ToolName]string` and `outputSchemas map[ToolName]any` to
  `Toolkit`, initialised in `NewToolkit`

### Gosec fixes (pre-existing issues)
- `pkg/client/config.go`: add `#nosec G117` to `SessionToken` field
- `pkg/multiserver/config.go`: add `#nosec G117` to `SessionToken` field;
  update `#nosec G304` → `#nosec G304 G703` on both `os.ReadFile` calls
- `pkg/client/client.go`: add `#nosec G118` to `context.WithTimeout` return
  (cancel func is intentionally returned to callers, not a leak)

### Documentation
- `docs/reference/tools-api.md`: align all response examples with actual
  output schemas (fix `body`→`content`, `encoding`→`is_base64`,
  `key_count`→`count`, `default`→`default_connection`, add missing fields)
- `docs/library/quickstart.md`: add "Tool Metadata Customization" section
  documenting `WithTitles`, `WithTitle`, `WithDescriptions`,
  `WithOutputSchemas`, and `WithOutputSchema`

All checks pass: `make verify` (lint, test, coverage ≥80%, security, deadcode, build-check)

Author: cjimti

docs/library/quickstart.md

@@ -96,6 +96,47 @@ cfg := &client.Config{
 s3Client, err := client.New(ctx, cfg)
 ```
 
+## Tool Metadata Customization
+
+Override titles, descriptions, annotations, icons, and output schemas at the toolkit level or per registration.
+
+### Toolkit-level overrides
+
+```go
+toolkit := tools.NewToolkit(s3Client,
+    // Override human-readable titles shown in MCP clients
+    tools.WithTitles(map[tools.ToolName]string{
+        tools.ToolListBuckets: "Browse Buckets",
+        tools.ToolGetObject:   "Fetch Object",
+    }),
+
+    // Override descriptions
+    tools.WithDescriptions(map[tools.ToolName]string{
+        tools.ToolListBuckets: "Show all buckets available to this service account.",
+    }),
+
+    // Override output schemas (JSON Schema 2020-12 as map[string]any)
+    tools.WithOutputSchemas(map[tools.ToolName]any{
+        tools.ToolListBuckets: map[string]any{
+            "type": "object",
+            "properties": map[string]any{
+                "buckets": map[string]any{"type": "array"},
+                "count":   map[string]any{"type": "integer"},
+            },
+        },
+    }),
+)
+```
+
+### Per-registration overrides
+
+```go
+toolkit.RegisterWith(mcpServer,
+    tools.ToolListBuckets, tools.WithTitle("Browse Buckets"),
+    tools.ToolGetObject,   tools.WithOutputSchema(customSchema),
+)
+```
+
 ## Multiple Connections
 
 ```go

docs/reference/tools-api.md

@@ -47,6 +47,8 @@ List objects in a bucket with optional filtering.
 
 ```json
 {
+  "bucket": "my-bucket",
+  "prefix": "path/to/",
   "objects": [
     {
       "key": "path/to/file.txt",
@@ -57,9 +59,9 @@ List objects in a bucket with optional filtering.
     }
   ],
   "common_prefixes": ["path/to/folder/"],
+  "count": 1,
   "is_truncated": false,
-  "next_continuation_token": null,
-  "key_count": 1
+  "next_continuation_token": null
 }
 ```
 
@@ -81,13 +83,15 @@ Retrieve object content.
 
 ```json
 {
+  "bucket": "my-bucket",
   "key": "path/to/file.txt",
   "content_type": "text/plain",
   "size": 1024,
   "last_modified": "2024-01-15T10:30:00Z",
   "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
-  "body": "File content here...",
-  "encoding": "text",
+  "content": "File content here...",
+  "is_base64": false,
+  "truncated": false,
   "metadata": {
     "custom-key": "custom-value"
   }
@@ -96,8 +100,8 @@ Retrieve object content.
 
 ### Notes
 
-- Text content is returned as-is
-- Binary content is returned as base64 with `encoding: "base64"`
+- Text content is returned as-is in `content`
+- Binary content is returned as base64 in `content` with `is_base64: true`
 - Objects larger than `MCP_S3_MAX_GET_SIZE` are rejected
 
 ---
@@ -118,6 +122,7 @@ Get object metadata without downloading content (HEAD request).
 
 ```json
 {
+  "bucket": "my-bucket",
   "key": "path/to/file.txt",
   "content_type": "text/plain",
   "content_length": 1024,
@@ -154,7 +159,8 @@ Upload an object to S3.
   "bucket": "my-bucket",
   "key": "path/to/file.txt",
   "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
-  "size": 1024
+  "size": 1024,
+  "version_id": "abc123"
 }
 ```
 
@@ -216,7 +222,9 @@ Copy an object within or between buckets.
   "source_key": "path/to/source.txt",
   "dest_bucket": "dest-bucket",
   "dest_key": "path/to/dest.txt",
-  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
+  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
+  "last_modified": "2024-01-15T10:30:00Z",
+  "version_id": "abc123"
 }
 ```
 
@@ -244,8 +252,11 @@ Generate a presigned URL for direct access.
 
 ```json
 {
+  "bucket": "my-bucket",
+  "key": "path/to/file.txt",
   "url": "https://bucket.s3.amazonaws.com/key?X-Amz-Algorithm=...",
   "method": "GET",
+  "expires_in_seconds": 3600,
   "expires_at": "2024-01-15T11:30:00Z"
 }
 ```
@@ -274,7 +285,8 @@ None.
       "endpoint": "http://localhost:8333"
     }
   ],
-  "default": "default"
+  "default_connection": "default",
+  "count": 2
 }
 ```
 

pkg/client/client.go

@@ -480,7 +480,7 @@ func (c *Client) contextWithTimeout(ctx context.Context) (context.Context, conte
 		}
 	}
 
-	return context.WithTimeout(ctx, c.config.Timeout)
+	return context.WithTimeout(ctx, c.config.Timeout) //#nosec G118 -- cancel func is returned to caller
 }
 
 // Close closes the S3 client and releases resources.

pkg/client/config.go

@@ -29,7 +29,7 @@ type Config struct {
 	SecretAccessKey string
 
 	// SessionToken is an optional session token for temporary credentials.
-	SessionToken string
+	SessionToken string //#nosec G117 -- field name is an AWS credential, not a secret exposure
 
 	// Profile is an optional AWS profile name to use from shared credentials/config.
 	Profile string

pkg/multiserver/config.go

@@ -28,7 +28,7 @@ type ConnectionConfig struct {
 	SecretAccessKey string `json:"secret_access_key,omitempty" yaml:"secret_access_key,omitempty"`
 
 	// SessionToken is an optional session token.
-	SessionToken string `json:"session_token,omitempty" yaml:"session_token,omitempty"`
+	SessionToken string `json:"session_token,omitempty" yaml:"session_token,omitempty"` //#nosec G117 -- AWS credential field
 
 	// Profile is an optional AWS profile name.
 	Profile string `json:"profile,omitempty" yaml:"profile,omitempty"`
@@ -94,7 +94,7 @@ func FromEnvJSON() (*MultiConfig, error) {
 
 // FromYAMLFile loads multi-connection configuration from a YAML file.
 func FromYAMLFile(path string) (*MultiConfig, error) {
-	data, err := os.ReadFile(path) //#nosec G304 -- Path is intentionally user-provided config file
+	data, err := os.ReadFile(path) //#nosec G304 G703 -- Path is intentionally user-provided config file
 	if err != nil {
 		return nil, err
 	}
@@ -109,7 +109,7 @@ func FromYAMLFile(path string) (*MultiConfig, error) {
 
 // FromJSONFile loads multi-connection configuration from a JSON file.
 func FromJSONFile(path string) (*MultiConfig, error) {
-	data, err := os.ReadFile(path) //#nosec G304 -- Path is intentionally user-provided config file
+	data, err := os.ReadFile(path) //#nosec G304 G703 -- Path is intentionally user-provided config file
 	if err != nil {
 		return nil, err
 	}

pkg/tools/annotations.go

@@ -18,45 +18,45 @@ var defaultAnnotations = map[ToolName]*mcp.ToolAnnotations{
 	ToolListBuckets: {
 		ReadOnlyHint:   true,
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 	ToolListConnections: {
 		ReadOnlyHint:   true,
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 	ToolListObjects: {
 		ReadOnlyHint:   true,
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 	ToolGetObject: {
 		ReadOnlyHint:   true,
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 	ToolGetObjectMetadata: {
 		ReadOnlyHint:   true,
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 	ToolPresignURL: {
 		ReadOnlyHint:  true,
-		OpenWorldHint: boolPtr(false),
+		OpenWorldHint: boolPtr(true),
 	},
 	ToolPutObject: {
 		DestructiveHint: boolPtr(false),
 		IdempotentHint:  true,
-		OpenWorldHint:   boolPtr(false),
+		OpenWorldHint:   boolPtr(true),
 	},
 	ToolCopyObject: {
 		DestructiveHint: boolPtr(false),
 		IdempotentHint:  true,
-		OpenWorldHint:   boolPtr(false),
+		OpenWorldHint:   boolPtr(true),
 	},
 	ToolDeleteObject: {
 		IdempotentHint: true,
-		OpenWorldHint:  boolPtr(false),
+		OpenWorldHint:  boolPtr(true),
 	},
 }
 

pkg/tools/annotations_test.go

@@ -82,14 +82,14 @@ func TestDefaultAnnotations(t *testing.T) {
 		}
 	})
 
-	t.Run("all tools are closed-world", func(t *testing.T) {
+	t.Run("all tools are open-world", func(t *testing.T) {
 		for _, name := range AllTools() {
 			ann := DefaultAnnotations(name)
 			if ann == nil {
 				t.Fatalf("tool %s has no default annotations", name)
 			}
-			if ann.OpenWorldHint == nil || *ann.OpenWorldHint {
-				t.Errorf("tool %s should have OpenWorldHint=false", name)
+			if ann.OpenWorldHint == nil || !*ann.OpenWorldHint {
+				t.Errorf("tool %s should have OpenWorldHint=true", name)
 			}
 		}
 	})

pkg/tools/connections.go

@@ -33,10 +33,12 @@ func (t *Toolkit) registerListConnectionsTool(server *mcp.Server, cfg *toolConfi
 	wrappedHandler := t.wrapHandler(ToolListConnections, baseHandler, cfg)
 
 	mcp.AddTool(server, &mcp.Tool{
-		Name:        t.toolName(ToolListConnections),
-		Description: t.getDescription(ToolListConnections, cfg),
-		Annotations: t.getAnnotations(ToolListConnections, cfg),
-		Icons:       t.getIcons(ToolListConnections, cfg),
+		Name:         t.toolName(ToolListConnections),
+		Title:        t.getTitle(ToolListConnections, cfg),
+		Description:  t.getDescription(ToolListConnections, cfg),
+		Annotations:  t.getAnnotations(ToolListConnections, cfg),
+		Icons:        t.getIcons(ToolListConnections, cfg),
+		OutputSchema: t.getOutputSchema(ToolListConnections, cfg),
 	}, func(ctx context.Context, req *mcp.CallToolRequest, input ListConnectionsInput) (*mcp.CallToolResult, *ListConnectionsResult, error) {
 		result, out, err := wrappedHandler(ctx, req, input)
 		if typed, ok := out.(*ListConnectionsResult); ok {

pkg/tools/copy_object.go

@@ -32,10 +32,12 @@ func (t *Toolkit) registerCopyObjectTool(server *mcp.Server, cfg *toolConfig) {
 	wrappedHandler := t.wrapHandler(ToolCopyObject, baseHandler, cfg)
 
 	mcp.AddTool(server, &mcp.Tool{
-		Name:        t.toolName(ToolCopyObject),
-		Description: t.getDescription(ToolCopyObject, cfg),
-		Annotations: t.getAnnotations(ToolCopyObject, cfg),
-		Icons:       t.getIcons(ToolCopyObject, cfg),
+		Name:         t.toolName(ToolCopyObject),
+		Title:        t.getTitle(ToolCopyObject, cfg),
+		Description:  t.getDescription(ToolCopyObject, cfg),
+		Annotations:  t.getAnnotations(ToolCopyObject, cfg),
+		Icons:        t.getIcons(ToolCopyObject, cfg),
+		OutputSchema: t.getOutputSchema(ToolCopyObject, cfg),
 	}, func(ctx context.Context, req *mcp.CallToolRequest, input CopyObjectInput) (*mcp.CallToolResult, *CopyObjectResult, error) {
 		result, out, err := wrappedHandler(ctx, req, input)
 		if typed, ok := out.(*CopyObjectResult); ok {

pkg/tools/delete_object.go

@@ -26,10 +26,12 @@ func (t *Toolkit) registerDeleteObjectTool(server *mcp.Server, cfg *toolConfig)
 	wrappedHandler := t.wrapHandler(ToolDeleteObject, baseHandler, cfg)
 
 	mcp.AddTool(server, &mcp.Tool{
-		Name:        t.toolName(ToolDeleteObject),
-		Description: t.getDescription(ToolDeleteObject, cfg),
-		Annotations: t.getAnnotations(ToolDeleteObject, cfg),
-		Icons:       t.getIcons(ToolDeleteObject, cfg),
+		Name:         t.toolName(ToolDeleteObject),
+		Title:        t.getTitle(ToolDeleteObject, cfg),
+		Description:  t.getDescription(ToolDeleteObject, cfg),
+		Annotations:  t.getAnnotations(ToolDeleteObject, cfg),
+		Icons:        t.getIcons(ToolDeleteObject, cfg),
+		OutputSchema: t.getOutputSchema(ToolDeleteObject, cfg),
 	}, func(ctx context.Context, req *mcp.CallToolRequest, input DeleteObjectInput) (*mcp.CallToolResult, *DeleteObjectResult, error) {
 		result, out, err := wrappedHandler(ctx, req, input)
 		if typed, ok := out.(*DeleteObjectResult); ok {