Agent bez narzędzi to chatbot. W pierwszym poście serii zdefiniowaliśmy narzędzia jako jeden z czterech filarów agenta. Teraz wejdziemy w szczegóły: jak agent sięga po narzędzia, jaki protokół za tym stoi i jak zarządzać tym, żeby 50 narzędzi nie zjadło całego okna kontekstowego.

Trzy warstwy narzędzi w Claude Code

Claude Code ma trzy źródła narzędzi, każde z innym mechanizmem i przeznaczeniem:

graph TD
    CC[Claude Code]

    subgraph "Warstwa 3: Skills"
        S1["/review"]
        S2["/security-review"]
        S3["Custom skills"]
    end

    subgraph "Warstwa 2: Serwery MCP"
        M1[GitHub MCP]
        M2[Context7]
        M3["Własne serwery"]
    end

    subgraph "Warstwa 1: Narzędzia wbudowane"
        R["Read / Edit / Write"]
        B["Bash / Grep / Glob"]
        A["Agent / TodoWrite"]
    end

    CC --> R
    CC --> M1
    CC --> S1
    R ~~~ M1
    M1 ~~~ S1

Warstwa 1: Narzędzia wbudowane

Wbudowane bezpośrednio w Claude Code. Zawsze dostępne, bez konfiguracji. Zoptymalizowane pod kątem tokenów — ich opisy są częścią systemu Claude Code i nie obciążają kontekstu w taki sam sposób jak MCP.

Przykłady: Read, Edit, Write, Bash, Grep, Glob, Agent, TodoWrite.

Warstwa 2: MCP (Model Context Protocol)

Zewnętrzne serwery dostarczające narzędzia przez standardowy protokół. Każdy serwer MCP to osobny proces (stdio) lub endpoint HTTP, który rejestruje swoje narzędzia (tools), zasoby (resources) i prompty (prompts).

Z perspektywy agenta MCP to dynamiczne rozszerzenie przestrzeni akcji. Bez MCP agent operuje na plikach i terminalu. Z MCP agent sięga po GitHub API, bazy danych, Notion, Slack, generatory obrazów — cokolwiek ktoś opakował w serwer MCP.

Warstwa 3: Skills

Skills to nie narzędzia w sensie MCP — to instrukcje behawioralne. Skill mówi agentowi "jak podejść do zadania", nie "jakie narzędzie wywołać". Gdy użytkownik pisze /review, Claude Code ładuje skill review, który zawiera zestaw instrukcji definiujących sposób pracy.

Jak skills są ładowane do kontekstu

Skills nie są ładowane do kontekstu na starcie sesji. W system prompcie pojawia się jedynie lista dostępnych skills — same nazwy z krótkimi opisami triggerów (kiedy dany skill powinien być użyty). Pełna treść skilla jest wstrzykiwana do kontekstu dopiero w momencie wywołania — gdy użytkownik wpisze slash command (/review) lub gdy model rozpozna trigger pasujący do opisu skilla.

Dzięki temu posiadanie wielu zdefiniowanych skills kosztuje minimalnie — lista nazw z opisami to zaledwie kilkadziesiąt tokenów, niezależnie od tego, ile instrukcji zawiera każdy skill. Token overhead rośnie dopiero w momencie faktycznego użycia skilla, ale jest jednorazowy (instrukcje ładowane raz na wywołanie, nie w każdej wiadomości).

Wbudowane skills vs custom skills

Claude Code ma zestaw wbudowanych skills, które są dostępne od razu:

• /review — code review pull requestu. Agent czyta diff, sprawdza testy, szuka problemów z bezpieczeństwem i jakością kodu.
• /security-review — audyt bezpieczeństwa zmian na bieżącej gałęzi. Agent analizuje kod pod kątem OWASP top 10, injection, wycieku danych.
• /init — inicjalizacja pliku CLAUDE.md z dokumentacją codebase'u. Agent eksploruje repozytorium i generuje instrukcje dla przyszłych sesji.
• /simplify — przegląd zmienionego kodu pod kątem powtórzeń, jakości i wydajności, a następnie automatyczna naprawa znalezionych problemów.

Oprócz wbudowanych możesz tworzyć custom skills. Każdy skill to katalog w .claude/skills/ zawierający plik SKILL.md:

.claude/
└── skills/
    └── deploy-check/
        └── SKILL.md

Plik SKILL.md zaczyna się od frontmatteru z dwoma polami: name (nazwa skilla, służy jako slash command) i description (krótki opis — to on pojawia się na liście dostępnych skills w kontekście). Reszta pliku to treść instrukcji w Markdown:

---
name: deploy-check
description: Sprawdź gotowość projektu do deployu — testy, env, migracje
---

# deploy-check

Sprawdź gotowość projektu do deployu:
1. Uruchom testy (`npm test`) i sprawdź czy przechodzą
2. Zweryfikuj zmienne środowiskowe w `.env.example` vs `.env`
3. Sprawdź czy migracje bazy danych są aktualne
4. Przejrzyj otwarte TODO/FIXME w zmienionych plikach

Po zapisaniu pliku skill pojawia się na liście dostępnych komend (/deploy-check) i może być wywołany jak wbudowany. Katalog skilla może też zawierać dodatkowe pliki (szablony, przykłady, konfiguracje) — SKILL.md może się do nich odwoływać w instrukcjach.

Dwa tryby uruchamiania

Skill może być uruchomiony na dwa sposoby:

1. Slash command — użytkownik jawnie wpisuje /review, /security-review itp.
2. Auto-trigger — skill ma w opisie warunki triggerowania (np. "TRIGGER when: code imports anthropic"), a model sam decyduje o jego załadowaniu, gdy rozpozna pasujący kontekst.

Skill może używać narzędzi (wbudowanych i MCP) wewnętrznie, ale sam narzędziem nie jest. Na przykład skill /review może wywołać Bash (żeby pobrać diff), Read (żeby przeczytać pliki) i narzędzia GitHub MCP (żeby sprawdzić komentarze do PR-a).

MCP pod lupą: jak działa

Jak MCP działa z perspektywy agenta

Mechanikę protokołu MCP — transport stdio/HTTP, trzy prymitywy (Tools, Resources, Prompts), konfigurację serwerów — opisaliśmy szczegółowo w serii MCP dla Claude . Tutaj skupiamy się na tym, co istotne z perspektywy agenta: co model widzi i jak to wpływa na jego rozumowanie.

Klient (Claude Code) na starcie sesji wstrzykuje do kontekstu modelu dwa rodzaje informacji z każdego serwera MCP:

1. Definicje narzędzi — schematy JSON z nazwą, opisem i parametrami. Bez schematu model nie wie, że narzędzie istnieje.
2. Instrukcje behawioralne serwera — tekst mówiący modelowi kiedy i jak używać narzędzi danego serwera (np. "sięgaj po dokumentację nawet gdy znasz bibliotekę — Twoje dane treningowe mogą być nieaktualne").

Z perspektywy modelu narzędzia MCP nie różnią się od wbudowanych — model generuje tool_call, klient routuje wywołanie do właściwego serwera, wynik wraca jako nowa percepcja. Model nie wie (i nie musi wiedzieć), czy narzędzie jest wbudowane, czy pochodzi z zewnętrznego serwera MCP.

Problem: token overhead

Każde narzędzie MCP ma opis (nazwa, dokumentacja, schemat parametrów JSON). Ten opis jest wstrzykiwany do kontekstu modelu na starcie sesji i pozostaje tam przez całą rozmowę — zajmuje miejsce niezależnie od tego, czy narzędzie zostanie użyte. Model musi "widzieć" narzędzie, żeby go użyć.

Oto skala problemu:

28 000 tokenów to ~14% okna 200k — lub ~2,8% okna 1M (Claude Sonnet 4.6 / Opus 4.6 od marca 2026). W każdej wiadomości. Zanim agent przeczyta choćby jeden plik, kontekst jest już zajęty opisami narzędzi, z których w danej chwili użyje może dwóch.

Rozwiązanie 1: Tool Search (deferred tools)

Claude Code rozwiązuje problem token overhead przez mechanizm Tool Search (deferred tools). Zamiast ładować schematy wszystkich narzędzi MCP na starcie, Claude Code:

1. Rejestruje nazwy narzędzi (bez schematów) — koszt: kilka tokenów per narzędzie
2. Gdy model chce użyć narzędzia, wywołuje ToolSearch(query="...")
3. ToolSearch zwraca pełne schematy dopasowanych narzędzi
4. Dopiero wtedy model może je wywołać

To oznacza, że 27 narzędzi domyślnych toolsetów GitHub MCP kosztuje ~135 tokenów (same nazwy) zamiast ~10 000 (pełne schematy). Schemat jest ładowany dopiero gdy model go potrzebuje.

graph TD
    A[Start sesji] --> B{Ile narzędzi MCP?}
    B -->|<10| C[Ładuj wszystko<br/>mały overhead]
    B -->|10+| D[Deferred: same nazwy<br/>~5 tokenów/narzędzie]
    D --> E[Model potrzebuje narzędzia]
    E --> F[ToolSearch query=...]
    F --> G[Załaduj schemat<br/>jednorazowo]
    G --> H[Model wywołuje narzędzie]

Kiedy Tool Search pomaga

• Masz wiele serwerów MCP z dziesiątkami narzędzi
• Większość narzędzi jest używana rzadko
• Chcesz "mieć pod ręką" GitHub MCP, ale nie płacić ~10k tokenów za same schematy

Kiedy nie pomaga

• Masz 2-3 serwery z kilkoma narzędziami (Context7, Sequential Thinking) — overhead jest i tak mały
• Narzędzie jest używane w prawie każdej wiadomości — ładowanie "na żądanie" dodaje opóźnienie

Rozwiązanie 2: Ograniczanie toolsetów

Wiele serwerów MCP pozwala na ograniczenie eksponowanych narzędzi. GitHub MCP ma flagę --toolsets:

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
  -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server \
  --toolsets repos,pull_requests

Zamiast ~27 narzędzi (domyślne toolsety) → ~10. Zamiast ~10 000 tokenów → ~4 000. A pokrywa 90% typowych use case'ów.

Analogicznie --read-only wyłącza narzędzia do zapisu (tworzenie PR-ów, komentarzy, merge'ów) — przydatne, gdy Claude ma tylko analizować, nie modyfikować.

Skills vs MCP — kiedy co

Skills i MCP to dwa mechanizmy rozszerzania agenta, ale służą różnym celom:

Praktyczna reguła:

• Potrzebujesz nowej akcji (wywołaj API, odpytaj bazę, wygeneruj obraz)? → MCP
• Potrzebujesz nowego zachowania (jak robić code review, jak pisać testy)? → Skill

Skill może używać narzędzi MCP wewnętrznie. Na przykład skill /review może wywołać GitHub MCP, żeby pobrać diff PR-a, a potem Context7, żeby sprawdzić dokumentację użytych bibliotek.

Budżet tokenów: ile narzędzi to za dużo?

Okno kontekstowe Claude Sonnet 4.6 / Opus 4.6 to 1M tokenów (od marca 2026; bazowe 200k dla starszych modeli). Oto jak się rozkłada typowa sesja:

Przy 3 serwerach MCP infrastruktura agenta zajmuje ~1.3% okna 1M — marginalnie. Ale przy starszych modelach z oknem 200k te same 13 000 tokenów to już ~6.5%. Problem zaczyna się, gdy dodajesz 10+ serwerów bez Tool Search: przy modelu 200k overhead rośnie do 20-30%, przy 1M do ~3-5% — w obu przypadkach oznacza to niepotrzebne zużycie kontekstu na opisy narzędzi, których agent i tak nie użyje.

Anatomia wywołania narzędzia

Jak wygląda jedno wywołanie narzędzia od strony technicznej:

sequenceDiagram
    participant M as Model
    participant CC as Claude Code
    participant H as Hook PreToolCall
    participant T as Narzędzie/MCP
    participant HP as Hook PostToolCall

    M->>CC: tool_call: Edit(file="src/app.py", ...)
    CC->>H: PreToolCall: Edit
    H-->>CC: OK (lub BLOCKED)
    CC->>CC: Sprawdź permissions
    CC->>CC: Pokaż użytkownikowi (jeśli wymaga approval)
    CC->>T: Wykonaj Edit
    T-->>CC: Wynik (sukces / błąd)
    CC->>HP: PostToolCall: Edit
    HP-->>CC: OK
    CC-->>M: Wynik → nowa percepcja

Zauważ pięć warstw kontroli:

1. Hooks PreToolCall — programowalna blokada/modyfikacja
2. System permissions — czy narzędzie wymaga potwierdzenia
3. User approval — czy użytkownik pozwolił (jeśli wymaga)
4. Wykonanie — faktyczna akcja
5. Hooks PostToolCall — reakcja na wynik (np. auto-format)

Praktyczne wzorce konfiguracji MCP

Minimalistyczny setup

Always-on:
  - Context7 (dokumentacja bibliotek)

On-demand:
  - GitHub MCP --toolsets repos,pull_requests (gdy pracujesz z PR-ami)

Pełny setup

Always-on:
  - Context7 (dokumentacja)
  - Sequential Thinking (planowanie)

On-demand:
  - GitHub MCP --toolsets repos,pull_requests,issues
  - PostgreSQL MCP (analiza danych)
  - Slack MCP (kontekst z rozmów zespołu)

Co dalej

W tym wpisie zobaczyliśmy, jak agent zarządza narzędziami: protokół MCP, problem token overhead i strategie optymalizacji (Tool Search, ograniczanie toolsetów, włączanie on-demand). W następnym poście zajmiemy się planowaniem i rozumowaniem — jak agent rozbija złożone zadania na kroki, kiedy planować a kiedy działać, i jak chain-of-thought wpływa na jakość wyników.