Opis narzędzia: jak go napisać i czego unikać
Po tej lekcji wiesz, co musi zawierać opis narzędzia, jak go napisać krok po kroku i jakie błędy najczęściej psują wybór narzędzia przez model.
W jednej minucie
Opis narzędzia to tekst w polu description, który mówi modelowi, co narzędzie robi, kiedy go użyć i jak się zachowuje1.
Opis to najważniejszy czynnik skuteczności narzędzia1. Pisz go tak, jakbyś tłumaczył narzędzie nowej osobie w zespole2.
Celuj w co najmniej 3–4 zdania na jeden opis1.
Co musi zawierać opis
Opis to jedno z pól definicji narzędzia, a odpowiada na cztery pytania.
| Element | Co opisujesz | Przykład |
|---|---|---|
| Co robi | Działanie narzędzia1 | Podaje bieżącą cenę akcji |
| Kiedy użyć | Kiedy go użyć, a kiedy nie1 | Gdy ktoś pyta o aktualną cenę konkretnej spółki |
| Parametry | Co znaczy każdy parametr i jak wpływa na działanie1 | ticker to symbol giełdowy, np. AAPL |
| Ograniczenia | Czego narzędzie nie zwraca, jeśli nazwa tego nie mówi1 | Nie podaje innych danych o spółce |
Przykłady dotyczą narzędzia get_stock_price z dokumentacji.
Kontekst, który masz w głowie, zapisz wprost: formaty zapytań, własną terminologię i relacje między zasobami2.
Dobry i zły opis
Dokumentacja porównuje dwa opisy tego samego narzędzia get_stock_price.
Dobry opis mówi, co narzędzie robi, kiedy go użyć, co zwraca i co znaczy parametr1. Zły jest zbyt krótki i zostawia modelowi wiele pytań1.
| Co mówi opis | Zły | Dobry |
|---|---|---|
| Co robi | ogólnikowo | jest |
| Kiedy użyć | brak | jest |
| Co zwraca | brak | jest |
Czym jest ticker | brak | jest |
| Czego nie robi | brak | jest |
Zestawienie to nasza ocena dwóch opisów z dokumentacji.
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}Jak napisać opis
Opis powstaje w próbach: piszesz, sprawdzasz na zadaniach i poprawiasz.
- Zacznij od nowej osoby w zespole. Wyobraź sobie, że tłumaczysz narzędzie komuś, kto nie zna Twojego projektu2.
- Zapisz ukryty kontekst. Formaty zapytań, własne pojęcia i relacje między zasobami podaj wprost2.
- Nazwij parametry jednoznacznie. Użyj
user_id, nieuser2, i opisz wejście oraz wyjście bez niejasności2. - Dodaj
input_examples, gdy wejście jest złożone1. - Sprawdź na zadaniach. Ewaluacja pozwala mierzyć skuteczność narzędzi2, a dużo błędów z niepoprawnymi parametrami sugeruje, że opis lub przykłady trzeba poprawić2.
Anthropic zauważył, że Claude niepotrzebnie dopisywał „2025” do zapytania w narzędziu wyszukiwania, co psuło wyniki. Poprawiono to ulepszonym opisem narzędzia2.
Liczba i nazwy narzędzi
Model musi też wybrać właściwe narzędzie z listy, a pomagają w tym dwie rzeczy: konsolidacja i przestrzeń nazw.
Konsolidacja to grupowanie powiązanych operacji w jedno narzędzie z parametrem action1. Mniej, ale bardziej wszechstronnych narzędzi zmniejsza niejednoznaczność wyboru1.
Przestrzeń nazw to wspólny prefiks z nazwą usługi, np. github_list_prs1. Pomaga wyznaczyć granice między wieloma narzędziami2.
| Zamiast | Rozważ |
|---|---|
create_pr, review_pr, merge_pr | Jedno narzędzie z parametrem action1 |
list_users, list_events, create_event | Jedno narzędzie schedule_event2 |
search w kilku usługach | Nazwy z prefiksem, np. asana_search i jira_search2 |
Przykłady zamian pochodzą z dokumentacji i artykułu Anthropic.
Częste błędy
Opis najczęściej zawodzi z pięciu powodów.
| Błąd | Skutek | Co zrobić |
|---|---|---|
| Zbyt krótki opis | Model dostaje wiele pytań bez odpowiedzi1 | Rozwiń opis do 3–4 zdań |
| Brak ograniczeń | Model nie wie, czego narzędzie nie zwraca1 | Dopisz, czego narzędzie nie robi |
| Nakładające się narzędzia | Agent nie wie, które wybrać2 | Scal je albo rozdziel zakresy |
Parametr user zamiast user_id | Wejście jest niejednoznaczne2 | Nazywaj parametr tym, czym jest |
| Błąd bez wskazówki | Kod błędu nie mówi, co poprawić2 | Napisz, co poszło nie tak i co spróbować |
Kolumna „Co zrobić” to nasza rada, nie cytat z dokumentacji.
Skrót zrozumiały w Twoim zespole nic nie mówi modelowi. Rozwiń terminy, formaty i relacje między zasobami2.
Pytania sprawdzające
Jakie cztery rzeczy powinien zawierać opis narzędzia?
Co narzędzie robi, kiedy go użyć (i kiedy nie), co znaczy każdy parametr oraz jakie ma ograniczenia, np. czego nie zwraca.
Opis get_stock_price brzmi „Gets the stock price for a ticker.”. Czego w nim brakuje?
Brakuje informacji, kiedy go użyć, co zwraca, co znaczy ticker i czego narzędzie nie robi. Dokumentacja nazywa taki opis zbyt krótkim.
Masz create_pr, review_pr i merge_pr. Jak ułatwisz modelowi wybór?
Łączysz je w jedno narzędzie z parametrem action. Mniej, ale bardziej wszechstronnych narzędzi zmniejsza niejednoznaczność wyboru.
Agent często błędnie wypełnia jeden parametr. Co sprawdzasz najpierw?
Opis narzędzia i nazwę parametru. Dużo błędów z niepoprawnymi parametrami sugeruje, że opis lub przykłady trzeba poprawić. Nazwij parametr jednoznacznie, np. user_id.
Podsumowanie
- Opis to najważniejszy czynnik skuteczności narzędzia.
- Opis mówi, co narzędzie robi, kiedy go użyć, co znaczą parametry i jakie ma ograniczenia.
- Pisz jak dla nowej osoby w zespole: ukryty kontekst zapisz wprost.
- Mniej, bardziej wszechstronnych narzędzi i prefiksy w nazwach ułatwiają wybór.
- Opis sprawdzaj na prawdziwych zadaniach i poprawiaj, gdy pojawiają się błędy.
Źródła
- Define tools — Claude Docssprawdzone 2026-11-02
- Writing effective tools for AI agents — Anthropic Engineeringsprawdzone 2026-11-02