Definicja narzędzia: co dokładnie widzi model
Po tej lekcji wiesz, z czego składa się definicja narzędzia, co z niej widzi model i jak zaprojektować wejście oraz wynik tak, żeby model je rozumiał.
W jednej minucie
Definicja narzędzia to obiekt, który opisuje narzędzie modelowi: ma nazwę, opis i schemat wejścia, a opcjonalnie przykłady wywołań. Wysyłasz ją w parametrze tools żądania1.
Nasza rekomendacja: zapisz w definicji wszystko, co model musi wiedzieć o narzędziu. API składa prompt systemowy m.in. z Twoich definicji1.
Opis (description) to najważniejsze pole definicji1.
Z czego składa się definicja
Definicja narzędzia to mały obiekt JSON z kilkoma polami.
| Pole | Co zawiera | Status |
|---|---|---|
name | Nazwa narzędzia. Musi pasować do wyrażenia ^[a-zA-Z0-9_-]{1,128}$1 | w definicji |
description | Opis: co narzędzie robi, kiedy go użyć i jak się zachowuje1 | w definicji |
input_schema | Obiekt JSON Schema z oczekiwanymi parametrami1 | w definicji |
input_examples | Przykładowe wejścia, które pokazują, jak użyć narzędzia1 | opcjonalne |
Podział na pola podstawowe i opcjonalne wynika z listy w dokumentacji.
Co dostaje model
Definicje trafiają do modelu w prompcie systemowym, który składa API.
Umowa z agentem
Narzędzie łączy system deterministyczny z agentem, który działa niedeterministycznie2.
Skoro model widzi tylko definicję, formaty, zakresy i wyjątki znane z kodu zapisz w opisie i schemacie.
Schemat wejścia
Schemat mówi, jakie argumenty model może przekazać do narzędzia.
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
}
},
"required": ["location"]
}
}To narzędzie oczekuje obiektu z wymaganym tekstem location i opcjonalnym unit, który może być tylko celsius albo fahrenheit1.
Każdy parametr ma własny opis. Parametr location pokazuje oczekiwany format na przykładzie1.
Nazywaj parametry jednoznacznie: user_id, nie user2.
Przykłady wejścia
Gdy wejście jest złożone, dodaj do definicji input_examples.
Dokumentacja wskazuje je dla narzędzi ze złożonym wejściem, zagnieżdżonymi obiektami i parametrami wrażliwymi na format1.
"input_examples": [
{ "location": "San Francisco, CA",
"unit": "fahrenheit" },
{ "location": "Tokyo, Japan",
"unit": "celsius" },
{ "location": "New York, NY" }
]Przykłady zwiększają prompt: o ok. 20–50 tokenów przy prostych i 100–200 przy złożonych obiektach1. Nie działają w narzędziach serwerowych, np. w wyszukiwarce1.
Każdy przykład musi pasować do input_schema. Przykład, który mu przeczy, kończy się błędem 400 z API1.
Co zwraca narzędzie
Definicja opisuje wejście, ale wynik wraca do modelu jako tool_result, więc jego kształt też projektujesz.
Dokumentacja radzi zwracać tylko informacje o wysokim sygnale1, czyli odpowiedź wysokosygnałową: tylko pola, których model potrzebuje do następnego kroku1. Zbędne dane marnują kontekst i utrudniają modelowi znalezienie tego, co ważne1.
Anthropic zaleca też unikać niskopoziomowych identyfikatorów, takich jak uuid czy mime_type2.
{
"user_id": "a8f3c2e1-9d4b",
"name": "Jane Kowalska",
"channel_id": "C04N7XQ2L",
"thread_ts": "1730450000.1234",
"mime_type": "text/plain",
"text": "Spotkanie w czwartek"
}{
"name": "Jane Kowalska",
"channel": "#projekt-acme",
"text": "Spotkanie w czwartek"
}Gdy agent czasem potrzebuje identyfikatorów, możesz dać mu parametr response_format, którym wybiera odpowiedź „concise” albo „detailed”2.
Oba JSON-y powyżej są poglądowe. Wymyśliliśmy je, żeby pokazać różnicę, i nie pochodzą z dokumentacji.
Częste błędy
Większość problemów z definicją narzędzia wynika z czterech rzeczy.
| Błąd | Skutek | Co zrobić |
|---|---|---|
| Nazwa spoza reguły | Nazwa musi pasować do ^[a-zA-Z0-9_-]{1,128}$1 | Używaj liter, cyfr, _ i - |
| Przykład niezgodny ze schematem | Błąd 400 z API1 | Sprawdzaj przykłady po każdej zmianie schematu |
Parametr user zamiast user_id | Wejście jest niejednoznaczne2 | Nazywaj parametr tym, czym jest |
| Wynik pełen pól technicznych | Marnuje kontekst modelu1 | Zwracaj tylko pola potrzebne do następnego kroku |
Kolumna „Co zrobić” to nasza rada, nie cytat z dokumentacji.
Pytania sprawdzające
Jakie pola ma definicja narzędzia i które z nich jest opcjonalne?
name, description i input_schema opisują narzędzie. input_examples jest opcjonalne i pokazuje poprawne wywołania.
Dlaczego wszystko, co wiesz o narzędziu, warto zapisać w jego definicji?
Bo model dostaje narzędzia w prompcie systemowym, który API składa z definicji. Czego w nich nie ma, tego model nie wie.
Dodajesz input_examples z przykładem, który nie pasuje do schematu. Co się stanie?
API zwróci błąd 400. Każdy przykład musi być zgodny z input_schema.
Narzędzie zwraca uuid, mime_type i trzy inne pola techniczne. Co poprawisz?
Zwrócisz tylko pola potrzebne do następnego kroku, np. name zamiast uuid. Jeśli agent potrzebuje identyfikatorów, dodasz parametr response_format.
Podsumowanie
- Definicja narzędzia to
name,description,input_schemai opcjonalnieinput_examples. - Model dostaje definicje w prompcie systemowym, który składa API.
input_schemaopisuje parametry, a każdy parametr dostaje własny, jednoznaczny opis.input_examplespokazują format wejścia, ale muszą pasować do schematu i kosztują tokeny.- Wynik narzędzia też projektujesz: zwracaj tylko pola potrzebne do następnego kroku.
Źródła
- Define tools — Claude Docssprawdzone 2026-11-02
- Writing effective tools for AI agents — Anthropic Engineeringsprawdzone 2026-11-02