Enhance toolbox documentation and fix import ordering

OskarStark · claude · OskarStark · commit 68d1e2cdf781 · 2025-09-17T22:21:44.000+02:00
- Add comprehensive examples for all 8 tools in README.md - Create table of contents with anchor links for easy navigation - Fix title underline in doc/index.rst and remove Component suffix - Reorder import statements in example files per coding standards 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/examples/aimlapi/toolcall.php b/examples/aimlapi/toolcall.php
@@ -11,13 +11,13 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\AiMlApi\Completions;
 use Symfony\AI\Platform\Bridge\AiMlApi\PlatformFactory;
 use Symfony\AI\Platform\Capability;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/anthropic/toolcall.php b/examples/anthropic/toolcall.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/bedrock/toolcall-claude.php b/examples/bedrock/toolcall-claude.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\Anthropic\Claude;
 use Symfony\AI\Platform\Bridge\Bedrock\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/bedrock/toolcall-nova.php b/examples/bedrock/toolcall-nova.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\Bedrock\Nova\Nova;
 use Symfony\AI\Platform\Bridge\Bedrock\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/dockermodelrunner/toolcall.php b/examples/dockermodelrunner/toolcall.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\DockerModelRunner\Completions;
 use Symfony\AI\Platform\Bridge\DockerModelRunner\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/mistral/toolcall-stream.php b/examples/mistral/toolcall-stream.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\YouTubeTranscriber;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\Mistral\Mistral;
 use Symfony\AI\Platform\Bridge\Mistral\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\YouTubeTranscriber;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/openai/toolcall-stream.php b/examples/openai/toolcall-stream.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Wikipedia;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Wikipedia;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/openai/toolcall.php b/examples/openai/toolcall.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\YouTubeTranscriber;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\YouTubeTranscriber;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/brave.php b/examples/toolbox/brave.php
@@ -11,13 +11,13 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Brave;
 use Symfony\AI\Agent\Toolbox\Tool\Crawler;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Brave;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/firecrawl-crawl.php b/examples/toolbox/firecrawl-crawl.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Firecrawl;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Firecrawl;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/firecrawl-map.php b/examples/toolbox/firecrawl-map.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Firecrawl;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Firecrawl;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/firecrawl-scrape.php b/examples/toolbox/firecrawl-scrape.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Firecrawl;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Firecrawl;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/mapbox-geocode.php b/examples/toolbox/mapbox-geocode.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Mapbox;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Mapbox;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/mapbox-reverse-geocode.php b/examples/toolbox/mapbox-reverse-geocode.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Mapbox;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Mapbox;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/serpapi.php b/examples/toolbox/serpapi.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\SerpApi;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\SerpApi;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/tavily.php b/examples/toolbox/tavily.php
@@ -11,12 +11,12 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
-use Symfony\AI\Toolbox\Tool\Tavily;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Toolbox\Tool\Tavily;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
diff --git a/examples/toolbox/weather-event.php b/examples/toolbox/weather-event.php
@@ -12,13 +12,13 @@
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Agent\Toolbox\AgentProcessor;
 use Symfony\AI\Agent\Toolbox\Event\ToolCallsExecuted;
-use Symfony\AI\Toolbox\Tool\OpenMeteo;
 use Symfony\AI\Agent\Toolbox\Toolbox;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 use Symfony\AI\Platform\Result\ObjectResult;
+use Symfony\AI\Toolbox\Tool\OpenMeteo;
 use Symfony\Component\EventDispatcher\EventDispatcher;
 
 require_once dirname(__DIR__).'/bootstrap.php';
diff --git a/src/toolbox/README.md b/src/toolbox/README.md
@@ -4,14 +4,14 @@ A collection of third-party tools for Symfony AI agents.
 
 ## Available Tools
 
-- **Brave Search**: Web search functionality using the Brave Search API
-- **Firecrawl**: Website scraping, crawling, and URL mapping capabilities
-- **Mapbox**: Geocoding and reverse geocoding services
-- **OpenMeteo**: Weather data and forecasting services
-- **SerpApi**: Internet search functionality via SerpApi
-- **Tavily**: Web search and content extraction services
-- **Wikipedia**: Search and retrieve Wikipedia articles
-- **YouTube Transcriber**: Fetch transcripts from YouTube videos
+- [**Brave Search**](#brave-search-tool): Web search functionality using the Brave Search API
+- [**Firecrawl**](#firecrawl-tool): Website scraping, crawling, and URL mapping capabilities
+- [**Mapbox**](#mapbox-tool): Geocoding and reverse geocoding services
+- [**OpenMeteo**](#openmeteo-tool): Weather data and forecasting services
+- [**SerpApi**](#serpapi-tool): Internet search functionality via SerpApi
+- [**Tavily**](#tavily-tool): Web search and content extraction services
+- [**Wikipedia**](#wikipedia-tool): Search and retrieve Wikipedia articles
+- [**YouTube Transcriber**](#youtube-transcriber-tool): Fetch transcripts from YouTube videos
 
 ## Installation
 
@@ -28,11 +28,90 @@ use Symfony\AI\Toolbox\Tool\Brave;
 use Symfony\Component\HttpClient\HttpClient;
 
 $httpClient = HttpClient::create();
-$brave = new Brave($httpClient, 'your-api-key');
+$brave = new Brave($httpClient, 'your-brave-api-key');
 
 $results = $brave('search query');
 ```
 
+### Firecrawl Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\Firecrawl;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$firecrawl = new Firecrawl($httpClient, 'your-api-key', 'https://api.firecrawl.dev');
+
+// Scrape a single page
+$scraped = $firecrawl->scrape('https://example.com');
+
+// Crawl an entire website
+$crawled = $firecrawl->crawl('https://example.com');
+
+// Map all URLs from a website
+$mapped = $firecrawl->map('https://example.com');
+```
+
+### Mapbox Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\Mapbox;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$mapbox = new Mapbox($httpClient, 'your-mapbox-access-token');
+
+// Convert address to coordinates
+$coordinates = $mapbox->geocode('1600 Pennsylvania Ave, Washington DC');
+
+// Convert coordinates to address
+$address = $mapbox->reverseGeocode(-77.0365, 38.8977);
+```
+
+### OpenMeteo Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\OpenMeteo;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$openMeteo = new OpenMeteo($httpClient);
+
+// Get current weather
+$currentWeather = $openMeteo->current(52.52, 13.4050); // Berlin coordinates
+
+// Get weather forecast
+$forecast = $openMeteo->forecast(52.52, 13.4050); // Berlin coordinates
+```
+
+### SerpApi Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\SerpApi;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$serpApi = new SerpApi($httpClient, 'your-serpapi-key');
+
+$results = $serpApi('artificial intelligence trends');
+```
+
+### Tavily Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\Tavily;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$tavily = new Tavily($httpClient, 'your-tavily-api-key');
+
+// Search for information
+$searchResults = $tavily->search('latest AI developments');
+
+// Extract content from a website
+$extractedContent = $tavily->extract(['https://example.com']);
+```
+
 ### Wikipedia Tool
 
 ```php
@@ -47,6 +126,22 @@ $searchResults = $wikipedia->search('artificial intelligence');
 
 // Get article content
 $article = $wikipedia->article('Artificial intelligence');
+
+// Use different language (optional)
+$germanWikipedia = new Wikipedia($httpClient, 'de');
+```
+
+### YouTube Transcriber Tool
+
+```php
+use Symfony\AI\Toolbox\Tool\YouTubeTranscriber;
+use Symfony\Component\HttpClient\HttpClient;
+
+$httpClient = HttpClient::create();
+$transcriber = new YouTubeTranscriber($httpClient);
+
+// Get transcript from YouTube video ID
+$transcript = $transcriber('dQw4w9WgXcQ');
 ```
 
 ## Requirements
diff --git a/src/toolbox/doc/index.rst b/src/toolbox/doc/index.rst
@@ -1,5 +1,5 @@
-Symfony AI - Toolbox Component
-===============================
+Symfony AI - Toolbox
+===================
 
 The Toolbox component provides a collection of third-party tools for AI agents, including web search and knowledge retrieval capabilities.
 
