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

# Tools

> List, inspect, and execute MCP tools through the Kontext client.

## List tools

`client.tools.list()` returns every tool available to your application. Each tool has an `id`, `name`, optional `description`, and optional `inputSchema` describing its parameters.

```typescript theme={"system"}
const tools = await client.tools.list();

for (const tool of tools) {
  console.log(tool.id, tool.description);
}
```

Tool ID format depends on where the tool comes from:

* Gateway-routed tools keep the ID returned by the gateway.
* Direct internal integration tools are normalized as `<integrationId>:<toolName>`.
* Single-endpoint mode usually uses the MCP server's tool names.

Always execute tools by IDs returned from `tools.list()`.

The `limit` option caps the gateway discovery query. It only applies in gateway mode; in other modes the parameter is ignored and all tools are returned.

```typescript theme={"system"}
const tools = await client.tools.list({ limit: 10 });
```

## Execute a tool

`client.tools.execute(toolId, args)` runs a tool and returns a `ToolResult` with a `content` string and the `raw` MCP response.

```typescript theme={"system"}
const [firstTool] = await client.tools.list();
if (!firstTool) throw new Error("No tools available");

const result = await client.tools.execute(firstTool.id, {});

console.log(result.content);
```

## Full example

```typescript theme={"system"}
import { createKontextClient } from "@kontext-dev/js-sdk/client";

const client = createKontextClient({
  clientId: "your-client-id",
  redirectUri: "http://localhost:3000/callback",
  onAuthRequired: (url) => {
    window.location.href = url.toString();
  },
});

await client.connect();

// Discover available tools
const tools = await client.tools.list();
console.log(`Found ${tools.length} tools`);

// Execute one
if (tools.length > 0) {
  const result = await client.tools.execute(tools[0].id, {});
  console.log(result.content);
}

await client.disconnect();
```

## Check integrations

`client.integrations.list()` returns the status of every integration attached to your application. Each entry tells you whether the user has connected that integration.

```typescript theme={"system"}
const integrations = await client.integrations.list();

for (const integration of integrations) {
  console.log(integration.name, integration.connected);
}
```

### Handle disconnected integrations

When `connected` is `false`, the `IntegrationInfo` object may include a `connectUrl` you can open so the user can complete connection steps. This can be OAuth authorization or API key (`user_token`) setup. It may also include a `reason` explaining why the integration is not connected.

```typescript theme={"system"}
const integrations = await client.integrations.list();
const disconnected = integrations.filter((i) => !i.connected);

for (const integration of disconnected) {
  console.log(`${integration.name}: ${integration.reason}`);
  if (integration.connectUrl) {
    // Open this URL for the user to complete connection
    window.open(integration.connectUrl);
  }
}
```

You can also handle this reactively through the `onIntegrationRequired` callback, which fires when a tool call fails because the integration is not connected:

```typescript theme={"system"}
const client = createKontextClient({
  clientId: "your-client-id",
  redirectUri: "http://localhost:3000/callback",
  onAuthRequired: (url) => { window.location.href = url.toString(); },
  onIntegrationRequired: (url, info) => {
    console.log(`Please connect ${info.name}`);
    window.open(url);
  },
});
```

## Tool shape reference

```typescript theme={"system"}
interface KontextTool {
  id: string;            // Unique tool identifier for this client runtime
  name: string;          // Display name
  description?: string;  // What the tool does
  inputSchema?: object;  // JSON Schema for the tool's arguments
  server?: {             // Present in hybrid mode
    id: string;
    name?: string;
  };
}

interface ToolResult {
  content: string;  // Extracted text content
  raw: unknown;     // Full MCP response
}
```

## Next steps

* [Authentication](/client/authentication) -- OAuth sign-in, callbacks, and session management.
* [Storage](/client/storage) -- Persist tokens across sessions with custom backends.
* [Client Types](/sdks/typescript/client) -- Full type reference for `KontextClient`, `KontextTool`, and `ToolResult`.