update tool docs

docs/servers/tools.mdx

@@ -66,23 +66,6 @@ def analyze_text(
     # Implementation...
 ```
 
-#### Supported Types
-
-FastMCP supports a wide range of type annotations:
-
-| Type Annotation         | Example                       | Description                         |
-| :---------------------- | :---------------------------- | :---------------------------------- |
-| Basic types             | `int`, `float`, `str`, `bool` | Simple scalar values                |
-| Container types         | `list[str]`, `dict[str, int]` | Collections of items                |
-| Optional types          | `Optional[float]`, `float\|None`| Parameters that may be null/omitted |
-| Union types             | `str \| int`, `Union[str, int]`| Parameters accepting multiple types |
-| Literal types           | `Literal["A", "B"]`           | Parameters with specific allowed values |
-| Pydantic models         | `UserData`                    | Complex structured data (see Structured Inputs) |
-
-<Tip>
-**Automatic JSON Parsing:** FastMCP intelligently handles arguments. If a client sends a string that looks like valid JSON (e.g., `"['a', 'b']"`) for a parameter hinted as a structured type (like `list[str]` or a Pydantic model), FastMCP will automatically attempt to parse the JSON string into the expected Python object before validation. This improves robustness when interacting with various clients.
-</Tip>
-
 #### Parameter Metadata
 
 You can provide additional metadata about parameters using Pydantic's `Field` class with `Annotated`. This approach is preferred as it's more modern and keeps type hints separate from validation rules:
@@ -124,6 +107,20 @@ Field provides several validation and documentation features:
 - `pattern`: Regex pattern for string validation
 - `default`: Default value if parameter is omitted
 
+#### Supported Types
+
+FastMCP supports a wide range of type annotations:
+
+| Type Annotation         | Example                       | Description                         |
+| :---------------------- | :---------------------------- | :---------------------------------- |
+| Basic types             | `int`, `float`, `str`, `bool` | Simple scalar values - see [Built-in Types](#built-in-types) |
+| Binary data             | `bytes`                       | Binary content - see [Binary Data Handling](#binary-data-handling) |
+| Collection types        | `list[str]`, `dict[str, int]`, `set[int]` | Collections of items - see [Collection Types](#collection-types) |
+| Optional types          | `float \| None`, `Optional[float]`| Parameters that may be null/omitted - see [Union and Optional Types](#union-and-optional-types) |
+| Union types             | `str \| int`, `Union[str, int]`| Parameters accepting multiple types - see [Union and Optional Types](#union-and-optional-types) |
+| Literal types           | `Literal["A", "B"]`           | Parameters with specific allowed values - see [Literal Types](#literal-types) |
+| Pydantic models         | `UserData`                    | Complex structured data - see [Pydantic Models](#pydantic-models) |
+
 #### Optional Arguments
 
 FastMCP follows Python's standard function parameter conventions. Parameters without default values are required, while those with default values are optional.
@@ -142,44 +139,6 @@ def search_products(
 
 In this example, the LLM must provide a `query` parameter, while `max_results`, `sort_by`, and `category` will use their default values if not explicitly provided.
 
-### Structured Inputs
-
-For tools requiring complex, nested, or well-validated inputs, use Pydantic models. Define a `BaseModel` and use it as a type hint for a parameter.
-
-```python
-from pydantic import BaseModel, Field
-from typing import Optional
-from datetime import date
-
-class ReservationRequest(BaseModel):
-    guest_name: str = Field(description="Full name of the guest making the reservation.")
-    check_in: date
-    check_out: date
-    room_type: Literal["standard", "deluxe", "suite"] = Field(default="standard", description="Type of room requested.")
-    guests: int = Field(gt=0, description="Number of guests (must be positive).")
-    special_requests: Optional[str] = Field(default=None, description="Any special requests for the stay.")
-
-@mcp.tool()
-def make_reservation(request: ReservationRequest) -> dict:
-    """Creates a new hotel reservation based on the provided details."""
-    # Pydantic automatically validates the incoming 'request' data
-    # against the ReservationRequest model before this function runs.
-    print(f"Making reservation for {request.guest_name}...")
-    # Implementation...
-    return {
-        "reservation_id": "R12345",
-        "status": "confirmed",
-        "guest": request.guest_name,
-        "dates": f"{request.check_in} to {request.check_out}"
-    }
-```
-
-Using Pydantic models provides:
-- Clear, self-documenting structure for complex inputs.
-- Built-in data validation (e.g., `gt=0`, date parsing).
-- Automatic generation of detailed JSON schemas for the LLM.
-- Easy handling of optional fields and default values.
-
 ### Metadata
 
 While FastMCP infers the name and description from your function, you can override these and add tags using arguments to the `@mcp.tool` decorator:
@@ -293,7 +252,7 @@ FastMCP automatically catches exceptions raised within your tool function:
 
 Using informative exceptions helps the LLM understand failures and react appropriately.
 
-### Using Context in Tools
+### Accessing MCP Context
 
 Tools can access MCP features like logging, reading resources, or reporting progress through the `Context` object. To use it, add a parameter to your tool function with the type hint `Context`.
 
@@ -365,4 +324,161 @@ The duplicate behavior options are:
 -   `"warn"` (default): Logs a warning and the new tool replaces the old one.
 -   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
 -   `"replace"`: Silently replaces the existing tool with the new one.
--   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
+-   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
+
+## Parameter Types
+
+FastMCP supports a wide variety of parameter types to give you flexibility when designing your tools. When clients send parameters, FastMCP will attempt to coerce values into the appropriate type when possible (for example, parsing JSON strings into structured types).
+
+### Built-in Types
+
+The most common parameter types are Python's built-in scalar types:
+
+```python
+@mcp.tool()
+def process_values(
+    name: str,             # Text data
+    count: int,            # Integer numbers
+    amount: float,         # Floating point numbers
+    enabled: bool          # Boolean values (True/False)
+):
+    """Process various value types."""
+    # Implementation...
+```
+
+These types provide clear expectations to the LLM about what values are acceptable and allow FastMCP to validate inputs properly. Even if a client provides a string like "42", it will be coerced to an integer for parameters annotated as `int`.
+
+### Collection Types
+
+For structured data collections, FastMCP supports standard Python collection types:
+
+```python
+@mcp.tool()
+def analyze_data(
+    values: list[float],           # List of numbers
+    labels: list[str],             # List of strings
+    properties: dict[str, str],    # Dictionary with string keys and values
+    mixed_data: dict[str, list[int]] # Nested collections
+):
+    """Analyze collections of data."""
+    # Implementation...
+```
+
+Collection types can be nested and combined to represent complex data structures. If a client sends a JSON string like `"[1.5, 2.5, 3.5]"` for a `list[float]` parameter, FastMCP will automatically parse and convert it.
+
+### Union and Optional Types
+
+For parameters that can accept multiple types or may be omitted:
+
+```python
+@mcp.tool()
+def flexible_search(
+    query: str | int,              # Can be either string or integer
+    filters: dict[str, str] | None = None,  # Optional dictionary
+    sort_field: str | None = None  # Optional string
+):
+    """Search with flexible parameter types."""
+    # Implementation...
+```
+
+Modern Python syntax (`str | int`) is preferred over older `Union[str, int]` forms. Similarly, `str | None` is preferred over `Optional[str]`.
+
+### Literal Types
+
+When a parameter must be one of a predefined set of values:
+
+```python
+from typing import Literal
+
+@mcp.tool()
+def sort_data(
+    data: list[float],
+    order: Literal["ascending", "descending"] = "ascending",
+    algorithm: Literal["quicksort", "mergesort", "heapsort"] = "quicksort"
+):
+    """Sort data using specified order and algorithm."""
+    # Implementation...
+```
+
+Literal types help LLMs understand exactly which values are acceptable and provide validation for incoming parameters.
+
+### Binary Data Handling
+
+There are two approaches to handling binary data in tool parameters:
+
+#### Using bytes type
+
+```python
+@mcp.tool()
+def process_binary(data: bytes):
+    """Process binary data directly.
+    
+    The client can send a binary string, which will be 
+    converted directly to bytes.
+    """
+    # Implementation using binary data
+    data_length = len(data)
+    # ...
+```
+
+When you annotate a parameter as `bytes`, FastMCP will:
+- Convert raw strings directly to bytes
+- Validate that the input can be properly represented as bytes
+
+FastMCP does not automatically decode base64-encoded strings for bytes parameters. If you need to accept base64-encoded data, you should handle the decoding manually as shown below.
+
+#### Using base64-encoded strings
+
+```python
+from typing import Annotated
+from pydantic import Field
+
+@mcp.tool()
+def process_image_data(
+    image_data: Annotated[str, Field(description="Base64-encoded image data")]
+):
+    """Process an image from base64-encoded string.
+    
+    The client is expected to provide base64-encoded data as a string.
+    You'll need to decode it manually.
+    """
+    # Manual base64 decoding
+    import base64
+    binary_data = base64.b64decode(image_data)
+    # Process binary_data...
+```
+
+This approach is recommended when you expect to receive base64-encoded binary data from clients.
+
+### Pydantic Models
+
+For complex, structured data with nested fields and validation, use Pydantic models:
+
+```python
+from pydantic import BaseModel, Field
+from typing import Optional
+
+class User(BaseModel):
+    username: str
+    email: str = Field(description="User's email address")
+    age: int | None = None
+    is_active: bool = True
+
+@mcp.tool()
+def create_user(user: User):
+    """Create a new user in the system."""
+    # The input is automatically validated against the User model
+    # Even if provided as a JSON string or dict
+    # Implementation...
+```
+
+Using Pydantic models provides:
+- Clear, self-documenting structure for complex inputs
+- Built-in data validation
+- Automatic generation of detailed JSON schemas for the LLM
+- Automatic conversion from dict/JSON input
+
+Clients can provide data for Pydantic model parameters as either:
+- A JSON object (string)
+- A dictionary with the appropriate structure
+- Nested parameters in the appropriate format

tests/server/test_server_interactions.py

@@ -195,6 +195,20 @@ class TestTools:
             assert result[0].mimeType == "image/png"
             assert result[0].data == base64.b64encode(b"fake png data").decode()
 
+    async def test_tool_with_invalid_input(self):
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def my_tool(x: int) -> int:
+            return x + 1
+
+        async with Client(mcp) as client:
+            with pytest.raises(
+                ClientError,
+                match="Input should be a valid integer, unable to parse string as an integer",
+            ):
+                await client.call_tool("my_tool", {"x": "not an int"})
+
 
 class TestResources:
     async def test_text_resource(self):