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

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Web search tools for Claude with the Anthropic API

> Give Claude web search and page fetch as tools on the Messages API: Keenable's tool definitions in Anthropic's format and a loop in Python and TypeScript.

Claude decides when to search the web or read a page, and your code runs each call with the Keenable SDK. This page gives you the two tool definitions in Anthropic's format and a complete loop for the Messages API.

## How the loop works

1. Your code sends the conversation and the Keenable tools to `client.messages.create`.
2. If Claude wants the web, the response has `stop_reason: "tool_use"` and one `tool_use` block per call, each with a `name`, an `id` and a decoded `input` object.
3. Your code runs each call with `run_tool_call` and sends every result back in one `user` message, as `tool_result` blocks with the matching `tool_use_id`.
4. When `stop_reason` is anything other than `tool_use`, the text blocks hold Claude's answer.

## Prerequisites

* An Anthropic API key in `ANTHROPIC_API_KEY`.
* Python 3 or Node.js with `tsx` to run the program.
* No Keenable key. The SDK searches without one. To raise the rate limit, set `KEENABLE_API_KEY` to an [API key](https://docs.keenable.ai/api-keys.md).

## Tool definition (copy verbatim)

Anthropic's Messages API takes each tool as `name`, `description` and `input_schema`. These are the Keenable SDK's definitions in that shape:

```json Anthropic Messages format theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
[
  {
    "name": "keenable_search",
    "description": "Search the web for current information. Returns ranked pages with their title, URL and extracted page text. Use this whenever the answer depends on recent events or facts you are unsure about.",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "What to look for, described in natural language rather than keywords."
        },
        "site": {
          "type": "string",
          "description": "Optional. Restrict results to one domain, e.g. 'arxiv.org'."
        },
        "exclude_domains": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional. Never return results from these hosts or their subdomains, e.g. 'pinterest.com'. Hosts only, no paths or wildcards. Up to 1,000."
        },
        "published_after": {
          "type": "string",
          "description": "Optional. Only pages published on or after this date (YYYY-MM-DD)."
        },
        "objective": {
          "type": "string",
          "description": "Optional. Two or three natural sentences, with no field labels and no line breaks, that cover: the exact facts, entities, numbers, dates or names a useful page must contain; task context the query does not state (who, where, when, eligibility, date window); which kinds of sources count or must be excluded; what is already established from earlier steps; and what is still unknown. Every sentence must be self-contained: name the entities, places, dates and figures explicitly, and never refer to 'the task', 'the clue', 'the question', 'above' or earlier results. Do not paste the conversation, and do not include personal, confidential or sensitive information. At most 1,000 characters."
        },
        "disable_cards": {
          "type": "boolean",
          "description": "Optional. true returns ordinary web pages in place of Keenable's cards (results Keenable writes for prices, exchange rates or company facts, whose URLs expire after one day). Default false."
        }
      },
      "required": [
        "query"
      ]
    }
  },
  {
    "name": "keenable_fetch",
    "description": "Fetch one web page and return its main content as markdown. Use after keenable_search when a search snippet is not enough.",
    "input_schema": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The URL of the page to read."
        }
      },
      "required": [
        "url"
      ]
    }
  }
]
```

The loop below builds this list from the SDK's `TOOLS` at run time, so the definitions always match the SDK version you installed. If you paste the JSON instead, check the SDK column of the [arguments table](https://docs.keenable.ai/tool-calling.md#tool-arguments): an older `run_tool_call` drops any argument its version doesn't offer.

## Run the loop

Install the Keenable SDK and Anthropic's SDK:

```bash TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
npm install keenable @anthropic-ai/sdk
```

```bash Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
pip install keenable anthropic
```

Save this program as `claude-tools.mts` or `claude_tools.py`. It asks a question, runs every tool call Claude makes, and prints the answer:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import Anthropic from "@anthropic-ai/sdk";
import { Keenable, KeenableError, TOOLS, runToolCall } from "keenable";

const keenable = new Keenable();
const client = new Anthropic(); // reads ANTHROPIC_API_KEY

// Build Anthropic tool definitions from the SDK's OpenAI-format TOOLS.
const tools: Anthropic.Tool[] = TOOLS.map((tool) => ({
  name: tool.function.name,
  description: tool.function.description,
  input_schema: tool.function.parameters as Anthropic.Tool.InputSchema,
}));

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "What changed in the latest Node.js LTS release? Cite your sources." },
];

while (true) {
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 16000,
    tools,
    messages,
  });
  if (response.stop_reason !== "tool_use") {
    for (const block of response.content) {
      if (block.type === "text") console.log(block.text);
    }
    break;
  }

  messages.push({ role: "assistant", content: response.content });
  const results: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type !== "tool_use") continue;
    try {
      const content = await runToolCall(keenable, block.name, block.input as Record<string, unknown>);
      results.push({ type: "tool_result", tool_use_id: block.id, content });
    } catch (error) {
      const content = `Tool call failed: ${error instanceof KeenableError ? error.message : error}`;
      results.push({ type: "tool_result", tool_use_id: block.id, content, is_error: true });
    }
  }
  // All results for one turn go back in a single user message.
  messages.push({ role: "user", content: results });
}
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import anthropic
from keenable import TOOLS, Keenable, KeenableError, run_tool_call

keenable = Keenable()
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

# Build Anthropic tool definitions from the SDK's OpenAI-format TOOLS.
tools = [
    {
        "name": tool["function"]["name"],
        "description": tool["function"]["description"],
        "input_schema": tool["function"]["parameters"],
    }
    for tool in TOOLS
]

messages = [
    {"role": "user", "content": "What changed in the latest Node.js LTS release? Cite your sources."}
]

while True:
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=16000, tools=tools, messages=messages
    )
    if response.stop_reason != "tool_use":
        for block in response.content:
            if block.type == "text":
                print(block.text)
        break

    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type != "tool_use":
            continue
        result = {"type": "tool_result", "tool_use_id": block.id}
        try:
            result["content"] = run_tool_call(keenable, block.name, block.input)
        except KeenableError as exc:
            result["content"] = f"Tool call failed: {exc}"
            result["is_error"] = True
        results.append(result)
    # All results for one turn go back in a single user message.
    messages.append({"role": "user", "content": results})
```

Run it with `npx tsx claude-tools.mts` or `python claude_tools.py`. The program prints Claude's final answer. The question asks for sources, so the answer names the pages Claude read.

If a tool call fails, for example on a page that can't be fetched, the `tool_result` block carries `is_error: true` and the error message, so Claude can try another URL or query. [Errors inside a tool call](https://docs.keenable.ai/tool-calling.md#errors-inside-a-tool-call) lists what `run_tool_call` raises.

## Differences from other providers

| Compared with | What changes on the Anthropic API |
| - | - |
| [OpenAI](https://docs.keenable.ai/tool-calling/openai.md) | The schema goes under `input_schema`, not `parameters`. Claude's arguments arrive decoded as `block.input`, not as a JSON string. You resend the whole conversation on every call instead of passing a previous response ID. |
| [Gemini](https://docs.keenable.ai/tool-calling/gemini.md) | Results go back as `tool_result` blocks inside a `user` message, not as standalone `function_result` items. Both flag a failed call with `is_error`. |
| [Mistral](https://docs.keenable.ai/tool-calling/mistral.md) | You can't pass the SDK's `TOOLS` as is: each definition needs mapping to `name`, `description` and `input_schema`. All results of one turn go in a single `user` message, not one `tool` message per call. |
| [Open models](https://docs.keenable.ai/tool-calling/open-models.md) | `max_tokens` is required on every request. Ollama and vLLM take the SDK's `TOOLS` unchanged. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.