> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> How to use tools from the client

Tools in MCP are server-implemented functions that enable AI models to perform specific actions. They represent capabilities that a server exposes to clients, allowing AI applications to interact with external systems, execute commands, or manipulate data.

## What are Tools?

Tools are well-defined functions with:

* **JSON Schema definitions** that specify their inputs and outputs
* **Single, focused operations** that perform one specific task
* **User approval requirement** before execution for security

Common examples include:

* File operations (read, write, delete)
* Web browsing and data fetching
* Database queries
* API calls to external services
* System commands

## Listing Available Tools

To see what tools are available from a connected MCP server:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from mcp_use import MCPClient

  async def list_tools():
      # Initialize client with server configuration
      config = {
          "mcpServers": {
              # Your server definitions here
          }
      }
      client = MCPClient(config)

      # Connect to servers
      await client.create_all_sessions()

      # Get a session for a specific server
      session = client.get_session("my_server")

      # List all available tools - always returns fresh data
      tools = await session.list_tools()

      for tool in tools:
          print(f"Tool: {tool.name}")
          print(f"Description: {tool.description}")
          print(f"Schema: {tool.inputSchema}")
          print("---")

  # Run the example
  asyncio.run(list_tools())
  ```
</CodeGroup>

### Automatic Tool List Update

When servers send `ToolListChangedNotification`, it signals that the tool list has changed. The `list_tools()` method always fetches fresh data from the server, ensuring you get up-to-date information.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server

    Note over Server: Server Changes State
    Server->>Server: disable(tool)
    Server->>Client: ToolListChangedNotification
    Client->>Client: Log notification

    Note over Client: User Calls list_tools()
    Client->>Server: list_tools()
    Server-->>Client: [updated tools]
    Client->>Client: Return fresh data
```

**Important:** Always use `await session.list_tools()` instead of the deprecated `session.tools` property to ensure you get fresh data:

<CodeGroup>
  ```python Python theme={null}
  # ✅ Recommended - always returns fresh data
  tools = await session.list_tools()

  # ⚠️ Deprecated - may return stale data
  # tools = session.tools
  ```
</CodeGroup>

## Calling Tools

Tools are executed using the `call_tool` method:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from mcp_use import MCPClient

  async def call_tool_example():
      config = {
          "mcpServers": {
              # Your server definitions here
          }
      }
      client = MCPClient(config)
      await client.create_all_sessions()

      session = client.get_session("filesystem_server")

      # Call a tool with arguments
      result = await session.call_tool(
          name="read_file",
          arguments={
              "path": "/path/to/file.txt",
              "encoding": "utf-8"
          }
      )

      # Handle the result
      if result.isError:
          print(f"Error: {result.content}")
      else:
          print(f"File content: {result.content}")

  asyncio.run(call_tool_example())
  ```
</CodeGroup>

## Tool Results

Tool calls return a `CallToolResult` object with:

* `content`: The result data or error message
* `isError`: Boolean indicating success or failure
* Additional metadata about the execution

<CodeGroup>
  ```python Python theme={null}
  # Example of handling tool results
  result = await session.call_tool("search_web", {"query": "MCP protocol"})

  if result.isError:
      print(f"Tool execution failed: {result.content}")
  else:
      # Process successful result
      for item in result.content:
          print(f"Found: {item}")
  ```
</CodeGroup>

## Error Handling

Always handle potential errors when calling tools:

<CodeGroup>
  ```python Python theme={null}
  try:
      result = await session.call_tool("risky_operation", {"param": "value"})
      if result.isError:
          print(f"Tool reported error: {result.content}")
      else:
          print(f"Success: {result.content}")
  except Exception as e:
      print(f"Connection or protocol error: {e}")
  ```
</CodeGroup>