rcrewai 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +24 -0
  3. data/README.md +133 -23
  4. data/ROADMAP.md +1 -1
  5. data/docs/api/agent.md +5 -2
  6. data/docs/api/configuration.md +36 -41
  7. data/docs/api/crew.md +34 -48
  8. data/docs/api/index.md +7 -0
  9. data/docs/api/task.md +10 -91
  10. data/docs/api/tools.md +19 -0
  11. data/docs/examples/api-integration.md +4 -4
  12. data/docs/examples/async-execution.md +4 -4
  13. data/docs/examples/code-review-crew.md +1 -1
  14. data/docs/examples/content-marketing-pipeline.md +3 -3
  15. data/docs/examples/custom-tools.md +8 -8
  16. data/docs/examples/customer-support.md +5 -5
  17. data/docs/examples/data-analysis-team.md +4 -4
  18. data/docs/examples/database-operations.md +4 -4
  19. data/docs/examples/ecommerce-operations.md +4 -4
  20. data/docs/examples/financial-analysis.md +3 -3
  21. data/docs/examples/hierarchical-crew.md +3 -2
  22. data/docs/examples/production-ready-crew.md +16 -10
  23. data/docs/examples/research-development.md +5 -5
  24. data/docs/examples/simple-research-crew.md +2 -2
  25. data/docs/examples/social-media.md +4 -4
  26. data/docs/examples/task-automation.md +2 -2
  27. data/docs/examples/tool-composition.md +42 -27
  28. data/docs/examples/web-scraping.md +6 -6
  29. data/docs/index.md +61 -44
  30. data/docs/tutorials/advanced-agents.md +194 -917
  31. data/docs/tutorials/agent-options.md +1 -1
  32. data/docs/tutorials/checkpointing.md +65 -0
  33. data/docs/tutorials/concurrency.md +57 -0
  34. data/docs/tutorials/custom-tools.md +198 -1143
  35. data/docs/tutorials/deployment.md +156 -155
  36. data/docs/tutorials/getting-started.md +69 -81
  37. data/docs/tutorials/index.md +19 -0
  38. data/docs/tutorials/interceptors-and-events.md +84 -0
  39. data/docs/tutorials/live-streaming.md +52 -0
  40. data/docs/tutorials/multiple-crews.md +70 -51
  41. data/docs/tutorials/providers.md +115 -0
  42. data/docs/upgrading-to-0.11.md +55 -0
  43. data/lib/rcrewai/agent.rb +0 -2
  44. data/lib/rcrewai/configuration.rb +64 -29
  45. data/lib/rcrewai/context_window.rb +12 -2
  46. data/lib/rcrewai/llm_clients/anthropic.rb +60 -9
  47. data/lib/rcrewai/llm_clients/base.rb +7 -0
  48. data/lib/rcrewai/llm_clients/bedrock.rb +29 -2
  49. data/lib/rcrewai/llm_clients/google.rb +36 -4
  50. data/lib/rcrewai/llm_clients/ollama.rb +17 -3
  51. data/lib/rcrewai/llm_clients/openai.rb +14 -1
  52. data/lib/rcrewai/llm_clients/openai_responses.rb +21 -2
  53. data/lib/rcrewai/pricing.rb +13 -3
  54. data/lib/rcrewai/tool_runner.rb +5 -1
  55. data/lib/rcrewai/version.rb +1 -1
  56. metadata +7 -1
@@ -1,1242 +1,297 @@
1
1
  ---
2
2
  layout: tutorial
3
3
  title: Custom Tools Development
4
- description: Learn how to build custom tools to extend agent capabilities for specialized tasks
4
+ description: Build custom tools with the tool DSL, so agents can call your code through native function calling
5
5
  ---
6
6
 
7
7
  # Custom Tools Development
8
8
 
9
- This tutorial teaches you how to create custom tools that extend agent capabilities beyond the built-in tools. You'll learn tool architecture, implementation patterns, testing strategies, and best practices.
9
+ A tool is a Ruby class the model can call. You declare its name, description, and
10
+ parameters, and write `execute`. RCrewAI turns the declaration into a JSON schema
11
+ for the provider, coerces the model's arguments to the declared types, and sends
12
+ the return value back to the model.
10
13
 
11
14
  ## Table of Contents
12
- 1. [Understanding Tool Architecture](#understanding-tool-architecture)
13
- 2. [Creating Basic Custom Tools](#creating-basic-custom-tools)
14
- 3. [Advanced Tool Features](#advanced-tool-features)
15
- 4. [API Integration Tools](#api-integration-tools)
16
- 5. [Database Tools](#database-tools)
17
- 6. [File Processing Tools](#file-processing-tools)
18
- 7. [Testing Custom Tools](#testing-custom-tools)
19
- 8. [Tool Security and Validation](#tool-security-and-validation)
15
+ 1. [Your First Tool](#your-first-tool)
16
+ 2. [Declaring Parameters](#declaring-parameters)
17
+ 3. [Configuring a Tool](#configuring-a-tool)
18
+ 4. [Calling an API](#calling-an-api)
19
+ 5. [Errors](#errors)
20
+ 6. [Thread Safety](#thread-safety)
21
+ 7. [Security](#security)
22
+ 8. [Testing Tools](#testing-tools)
23
+ 9. [Tools Without the DSL](#tools-without-the-dsl)
24
+ 10. [Best Practices](#best-practices)
25
+
26
+ ## Your First Tool
20
27
 
21
- ## Understanding Tool Architecture
22
-
23
- ### Tool Base Class
28
+ ```ruby
29
+ require 'rcrewai'
24
30
 
25
- All tools in RCrewAI inherit from the base Tool class:
31
+ class WordCount < RCrewAI::Tools::Base
32
+ tool_name 'word_count'
33
+ description 'Count the words in a piece of text'
34
+ param :text, type: :string, required: true, description: 'The text to count'
26
35
 
27
- ```ruby
28
- module RCrewAI
29
- module Tools
30
- class Base
31
- attr_reader :name, :description
32
-
33
- def initialize(**options)
34
- @name = self.class.name.split('::').last.downcase
35
- @description = "Base tool description"
36
- @options = options
37
- @logger = Logger.new($stdout)
38
- end
39
-
40
- def execute(**params)
41
- raise NotImplementedError, "Subclasses must implement execute method"
42
- end
43
-
44
- def validate_params!(params, required: [], optional: [])
45
- # Built-in parameter validation
46
- required.each do |param|
47
- unless params.key?(param)
48
- raise ToolError, "Missing required parameter: #{param}"
49
- end
50
- end
51
-
52
- # Check for unknown parameters
53
- all_params = required + optional
54
- params.keys.each do |key|
55
- unless all_params.include?(key)
56
- raise ToolError, "Unknown parameter: #{key}"
57
- end
58
- end
59
- end
60
- end
36
+ def execute(text:)
37
+ text.split.length.to_s
61
38
  end
62
39
  end
63
- ```
64
40
 
65
- ### Tool Lifecycle
41
+ agent = RCrewAI::Agent.new(
42
+ name: 'editor',
43
+ role: 'Editor',
44
+ goal: 'Keep articles within their word limits',
45
+ tools: [WordCount.new]
46
+ )
47
+ ```
66
48
 
67
- 1. **Initialization**: Tool is created with configuration
68
- 2. **Validation**: Parameters are validated before execution
69
- 3. **Execution**: Tool performs its function
70
- 4. **Result Formatting**: Output is formatted for agent consumption
71
- 5. **Error Handling**: Exceptions are caught and handled
49
+ Three things matter here:
72
50
 
73
- ## Creating Basic Custom Tools
51
+ - **The description is for the model.** It decides whether the tool gets called, so
52
+ say what the tool does and when to use it.
53
+ - **`execute` receives keyword arguments**, one for each declared parameter.
54
+ - **Return a string.** Other values are converted with `to_s` before the model sees them.
74
55
 
75
- ### Simple Calculator Tool
56
+ You can call a tool directly to try it:
76
57
 
77
58
  ```ruby
78
- class CalculatorTool < RCrewAI::Tools::Base
79
- def initialize(**options)
80
- super
81
- @name = 'calculator'
82
- @description = 'Performs mathematical calculations'
83
- @precision = options[:precision] || 2
84
- end
85
-
86
- def execute(**params)
87
- validate_params!(params, required: [:operation, :operands])
88
-
89
- operation = params[:operation].to_s.downcase
90
- operands = params[:operands]
91
-
92
- # Validate operands
93
- unless operands.is_a?(Array) && operands.all? { |o| o.is_a?(Numeric) }
94
- raise ToolError, "Operands must be an array of numbers"
95
- end
96
-
97
- result = case operation
98
- when 'add', '+'
99
- operands.sum
100
- when 'subtract', '-'
101
- operands.reduce(&:-)
102
- when 'multiply', '*'
103
- operands.reduce(&:*)
104
- when 'divide', '/'
105
- divide_with_check(operands)
106
- when 'power', '^'
107
- operands[0] ** operands[1]
108
- when 'sqrt'
109
- Math.sqrt(operands[0])
110
- when 'average'
111
- operands.sum.to_f / operands.length
112
- else
113
- raise ToolError, "Unknown operation: #{operation}"
114
- end
115
-
116
- format_result(result)
117
- end
118
-
119
- private
120
-
121
- def divide_with_check(operands)
122
- if operands[1..-1].any? { |o| o == 0 }
123
- raise ToolError, "Division by zero"
124
- end
125
- operands.reduce(&:/)
126
- end
127
-
128
- def format_result(result)
129
- if result.is_a?(Float)
130
- "Result: #{result.round(@precision)}"
131
- else
132
- "Result: #{result}"
133
- end
134
- end
135
- end
136
-
137
- # Usage with an agent
138
- calculator = CalculatorTool.new(precision: 4)
139
-
140
- agent = RCrewAI::Agent.new(
141
- name: "math_agent",
142
- role: "Mathematics Specialist",
143
- goal: "Solve mathematical problems",
144
- tools: [calculator]
145
- )
146
-
147
- # Agent can now use: USE_TOOL[calculator](operation=multiply, operands=[5, 3, 2])
59
+ WordCount.new.execute(text: 'one two three') # => "3"
60
+ WordCount.json_schema
61
+ # => { name: "word_count", description: "Count the words in a piece of text",
62
+ # parameters: { type: "object", properties: { text: { ... } }, required: ["text"] } }
148
63
  ```
149
64
 
150
- ### Weather Information Tool
65
+ ## Declaring Parameters
151
66
 
152
67
  ```ruby
153
- require 'net/http'
154
- require 'json'
68
+ class SearchOrders < RCrewAI::Tools::Base
69
+ tool_name 'search_orders'
70
+ description 'Search customer orders'
155
71
 
156
- class WeatherTool < RCrewAI::Tools::Base
157
- def initialize(**options)
158
- super
159
- @name = 'weather'
160
- @description = 'Get current weather information for any location'
161
- @api_key = options[:api_key] || ENV['WEATHER_API_KEY']
162
- @base_url = 'https://api.openweathermap.org/data/2.5'
163
- @units = options[:units] || 'metric' # metric, imperial, kelvin
164
- end
165
-
166
- def execute(**params)
167
- validate_params!(params, required: [:location], optional: [:forecast])
168
-
169
- location = params[:location]
170
- forecast = params[:forecast] || false
171
-
172
- begin
173
- if forecast
174
- get_forecast(location)
175
- else
176
- get_current_weather(location)
177
- end
178
- rescue => e
179
- "Weather service error: #{e.message}"
180
- end
181
- end
182
-
183
- private
184
-
185
- def get_current_weather(location)
186
- endpoint = "#{@base_url}/weather"
187
- params = {
188
- q: location,
189
- appid: @api_key,
190
- units: @units
191
- }
192
-
193
- response = make_api_request(endpoint, params)
194
- format_weather_response(response)
195
- end
196
-
197
- def get_forecast(location)
198
- endpoint = "#{@base_url}/forecast"
199
- params = {
200
- q: location,
201
- appid: @api_key,
202
- units: @units,
203
- cnt: 5 # 5 day forecast
204
- }
205
-
206
- response = make_api_request(endpoint, params)
207
- format_forecast_response(response)
208
- end
209
-
210
- def make_api_request(endpoint, params)
211
- uri = URI(endpoint)
212
- uri.query = URI.encode_www_form(params)
213
-
214
- http = Net::HTTP.new(uri.host, uri.port)
215
- http.use_ssl = true
216
- http.read_timeout = 10
217
-
218
- request = Net::HTTP::Get.new(uri)
219
- response = http.request(request)
220
-
221
- if response.code == '200'
222
- JSON.parse(response.body)
223
- else
224
- raise "API error: #{response.code} - #{response.body}"
225
- end
226
- end
227
-
228
- def format_weather_response(data)
229
- temp = data['main']['temp']
230
- feels_like = data['main']['feels_like']
231
- description = data['weather'][0]['description']
232
- humidity = data['main']['humidity']
233
- wind_speed = data['wind']['speed']
234
-
235
- unit_label = @units == 'metric' ? '°C' : '°F'
236
-
237
- <<~WEATHER
238
- Weather in #{data['name']}, #{data['sys']['country']}:
239
- Temperature: #{temp}#{unit_label} (feels like #{feels_like}#{unit_label})
240
- Conditions: #{description}
241
- Humidity: #{humidity}%
242
- Wind Speed: #{wind_speed} #{@units == 'metric' ? 'm/s' : 'mph'}
243
- WEATHER
244
- end
245
-
246
- def format_forecast_response(data)
247
- forecasts = data['list'].map do |item|
248
- time = Time.at(item['dt']).strftime('%Y-%m-%d %H:%M')
249
- temp = item['main']['temp']
250
- desc = item['weather'][0]['description']
251
- "#{time}: #{temp}°, #{desc}"
252
- end
253
-
254
- "5-Day Forecast for #{data['city']['name']}:\n" + forecasts.join("\n")
72
+ param :query, type: :string, required: true, description: 'Customer name or order number'
73
+ param :limit, type: :integer, default: 10, description: 'Maximum results to return'
74
+ param :status, type: :enum, values: %w[open shipped cancelled]
75
+ param :tags, type: :array, items: { type: :string }
76
+ param :open_only, type: :boolean
77
+ param :filters, type: :object, properties: { min_total: { type: 'number' } }
78
+
79
+ def execute(query:, limit: 10, status: nil, tags: [], open_only: false, filters: {})
80
+ "Found 0 orders for #{query} (limit #{limit}, status #{status.inspect})"
255
81
  end
256
82
  end
257
83
  ```
258
84
 
259
- ## Advanced Tool Features
85
+ The supported types are `:string`, `:integer`, `:number`, `:boolean`, `:array`,
86
+ `:object`, and `:enum`.
260
87
 
261
- ### Tool with State Management
88
+ **`default:` only informs the model.** It appears in the schema, but RCrewAI doesn't
89
+ fill it in when the model leaves the argument out, so also give the keyword a default
90
+ in `execute`, as `limit: 10` does above. Every parameter that isn't `required: true`
91
+ needs one.
262
92
 
263
- ```ruby
264
- class SessionMemoryTool < RCrewAI::Tools::Base
265
- def initialize(**options)
266
- super
267
- @name = 'session_memory'
268
- @description = 'Store and retrieve information during agent session'
269
- @memory_store = {}
270
- @max_entries = options[:max_entries] || 100
271
- @ttl = options[:ttl] || 3600 # 1 hour default
272
- end
273
-
274
- def execute(**params)
275
- validate_params!(params,
276
- required: [:action],
277
- optional: [:key, :value, :pattern]
278
- )
279
-
280
- action = params[:action].to_sym
281
-
282
- case action
283
- when :store
284
- store_value(params[:key], params[:value])
285
- when :retrieve
286
- retrieve_value(params[:key])
287
- when :delete
288
- delete_value(params[:key])
289
- when :list
290
- list_keys(params[:pattern])
291
- when :clear
292
- clear_all
293
- else
294
- raise ToolError, "Unknown action: #{action}"
295
- end
296
- end
297
-
298
- private
299
-
300
- def store_value(key, value)
301
- raise ToolError, "Key and value required for store action" unless key && value
302
-
303
- # Enforce size limit
304
- if @memory_store.size >= @max_entries && !@memory_store.key?(key)
305
- evict_oldest
306
- end
307
-
308
- @memory_store[key] = {
309
- value: value,
310
- timestamp: Time.now,
311
- access_count: 0
312
- }
313
-
314
- "Stored: #{key} = #{value}"
315
- end
316
-
317
- def retrieve_value(key)
318
- raise ToolError, "Key required for retrieve action" unless key
319
-
320
- if entry = @memory_store[key]
321
- # Check TTL
322
- if Time.now - entry[:timestamp] > @ttl
323
- @memory_store.delete(key)
324
- return "Key expired: #{key}"
325
- end
326
-
327
- entry[:access_count] += 1
328
- entry[:last_accessed] = Time.now
329
-
330
- "Retrieved: #{key} = #{entry[:value]} (accessed #{entry[:access_count]} times)"
331
- else
332
- "Key not found: #{key}"
333
- end
334
- end
335
-
336
- def delete_value(key)
337
- if @memory_store.delete(key)
338
- "Deleted: #{key}"
339
- else
340
- "Key not found: #{key}"
341
- end
342
- end
343
-
344
- def list_keys(pattern = nil)
345
- keys = @memory_store.keys
346
-
347
- if pattern
348
- regex = Regexp.new(pattern)
349
- keys = keys.select { |k| k.match?(regex) }
350
- end
351
-
352
- "Keys (#{keys.length}): #{keys.join(', ')}"
353
- end
354
-
355
- def clear_all
356
- count = @memory_store.size
357
- @memory_store.clear
358
- "Cleared #{count} entries"
359
- end
360
-
361
- def evict_oldest
362
- oldest = @memory_store.min_by { |k, v| v[:last_accessed] || v[:timestamp] }
363
- @memory_store.delete(oldest[0]) if oldest
364
- end
365
- end
366
- ```
93
+ Arguments are coerced before `execute` runs, so `"5"` becomes `5` for an `:integer`.
94
+ A value that can't be coerced, or a missing required parameter, raises
95
+ `RCrewAI::Tools::ToolError`.
96
+
97
+ The tool name defaults to the class name in snake case, so `tool_name` is optional
98
+ for `SearchOrders`.
367
99
 
368
- ### Async Tool with Callbacks
100
+ ## Configuring a Tool
101
+
102
+ Put setup such as credentials and limits in `initialize`, not in parameters the
103
+ model can see. Call `super()` with empty parentheses, because the base class takes
104
+ no arguments:
369
105
 
370
106
  ```ruby
371
- class AsyncProcessingTool < RCrewAI::Tools::Base
372
- def initialize(**options)
373
- super
374
- @name = 'async_processor'
375
- @description = 'Process tasks asynchronously with progress tracking'
376
- @callback = options[:callback]
377
- @thread_pool = []
378
- @max_threads = options[:max_threads] || 5
379
- end
380
-
381
- def execute(**params)
382
- validate_params!(params,
383
- required: [:task_type, :data],
384
- optional: [:priority, :timeout]
385
- )
386
-
387
- task_id = SecureRandom.uuid
388
- priority = params[:priority] || :normal
389
- timeout = params[:timeout] || 60
390
-
391
- # Start async processing
392
- thread = Thread.new do
393
- begin
394
- process_async(task_id, params[:task_type], params[:data], timeout)
395
- rescue => e
396
- handle_async_error(task_id, e)
397
- end
398
- end
399
-
400
- # Manage thread pool
401
- @thread_pool << thread
402
- cleanup_threads
403
-
404
- "Task queued: #{task_id} (priority: #{priority})"
405
- end
406
-
407
- def get_status(task_id)
408
- # Check task status
409
- if result = check_result(task_id)
410
- "Task #{task_id}: #{result[:status]} - #{result[:message]}"
411
- else
412
- "Task #{task_id}: Unknown or not started"
413
- end
414
- end
415
-
416
- private
417
-
418
- def process_async(task_id, task_type, data, timeout)
419
- update_status(task_id, :processing, "Started at #{Time.now}")
420
-
421
- result = Timeout::timeout(timeout) do
422
- case task_type
423
- when 'analysis'
424
- perform_analysis(data)
425
- when 'transformation'
426
- perform_transformation(data)
427
- when 'validation'
428
- perform_validation(data)
429
- else
430
- raise "Unknown task type: #{task_type}"
431
- end
432
- end
433
-
434
- update_status(task_id, :completed, result)
435
-
436
- # Execute callback if provided
437
- @callback.call(task_id, result) if @callback
438
-
439
- rescue Timeout::Error
440
- update_status(task_id, :timeout, "Task exceeded #{timeout}s limit")
441
- end
442
-
443
- def cleanup_threads
444
- @thread_pool.reject!(&:alive?)
445
-
446
- # Limit thread pool size
447
- while @thread_pool.size > @max_threads
448
- oldest = @thread_pool.shift
449
- oldest.join(1) # Wait 1 second then continue
450
- end
451
- end
452
-
453
- def update_status(task_id, status, message)
454
- @status_store ||= {}
455
- @status_store[task_id] = {
456
- status: status,
457
- message: message,
458
- timestamp: Time.now
459
- }
107
+ class InvoiceLookup < RCrewAI::Tools::Base
108
+ tool_name 'invoice_lookup'
109
+ description 'Look up an invoice by its number'
110
+ param :number, type: :string, required: true
111
+
112
+ def initialize(client:, max_age_days: 90)
113
+ super()
114
+ @client = client
115
+ @max_age_days = max_age_days
460
116
  end
461
-
462
- def check_result(task_id)
463
- @status_store&.[](task_id)
117
+
118
+ def execute(number:)
119
+ @client.find_invoice(number, max_age_days: @max_age_days).to_s
464
120
  end
465
121
  end
466
122
  ```
467
123
 
468
- ## API Integration Tools
124
+ ## Calling an API
469
125
 
470
- ### REST API Client Tool
126
+ Tools can use any HTTP client. Faraday is already a dependency of the gem:
471
127
 
472
128
  ```ruby
473
129
  require 'faraday'
474
130
  require 'json'
475
131
 
476
- class RestApiTool < RCrewAI::Tools::Base
477
- def initialize(**options)
478
- super
479
- @name = 'rest_api'
480
- @description = 'Make REST API calls with authentication and error handling'
481
- @base_url = options[:base_url]
482
- @api_key = options[:api_key]
483
- @auth_type = options[:auth_type] || :header # :header, :query, :basic
484
- @timeout = options[:timeout] || 30
485
-
486
- setup_client
487
- end
488
-
489
- def execute(**params)
490
- validate_params!(params,
491
- required: [:method, :endpoint],
492
- optional: [:data, :headers, :query]
493
- )
494
-
495
- method = params[:method].to_s.downcase.to_sym
496
- endpoint = params[:endpoint]
497
- data = params[:data]
498
- headers = params[:headers] || {}
499
- query = params[:query] || {}
500
-
501
- # Add authentication
502
- headers, query = add_authentication(headers, query)
503
-
504
- # Make request
505
- response = make_request(method, endpoint, data, headers, query)
506
-
507
- # Format response
508
- format_api_response(response)
509
- rescue Faraday::Error => e
510
- handle_api_error(e)
511
- end
512
-
513
- private
514
-
515
- def setup_client
516
- @client = Faraday.new(url: @base_url) do |f|
517
- f.request :json
518
- f.response :json
519
- f.adapter Faraday.default_adapter
520
- f.options.timeout = @timeout
521
-
522
- # Add middleware for logging
523
- f.response :logger if @options[:debug]
524
-
525
- # Add retry logic
526
- f.request :retry, {
527
- max: 3,
528
- interval: 0.5,
529
- interval_randomness: 0.5,
530
- backoff_factor: 2
531
- }
532
- end
533
- end
534
-
535
- def add_authentication(headers, query)
536
- case @auth_type
537
- when :header
538
- headers['Authorization'] = "Bearer #{@api_key}" if @api_key
539
- when :query
540
- query['api_key'] = @api_key if @api_key
541
- when :basic
542
- headers['Authorization'] = "Basic #{Base64.encode64(@api_key)}" if @api_key
543
- end
544
-
545
- [headers, query]
546
- end
547
-
548
- def make_request(method, endpoint, data, headers, query)
549
- case method
550
- when :get
551
- @client.get(endpoint, query, headers)
552
- when :post
553
- @client.post(endpoint, data, headers) do |req|
554
- req.params = query
555
- end
556
- when :put
557
- @client.put(endpoint, data, headers) do |req|
558
- req.params = query
559
- end
560
- when :patch
561
- @client.patch(endpoint, data, headers) do |req|
562
- req.params = query
563
- end
564
- when :delete
565
- @client.delete(endpoint, query, headers)
566
- else
567
- raise ToolError, "Unsupported HTTP method: #{method}"
568
- end
569
- end
570
-
571
- def format_api_response(response)
572
- status = response.status
573
- body = response.body
574
-
575
- if status >= 200 && status < 300
576
- if body.is_a?(Hash) || body.is_a?(Array)
577
- JSON.pretty_generate(body)
578
- else
579
- body.to_s
580
- end
581
- else
582
- "API Error (#{status}): #{body}"
583
- end
132
+ class Weather < RCrewAI::Tools::Base
133
+ tool_name 'weather'
134
+ description 'Get the current weather for a city'
135
+ param :city, type: :string, required: true, description: 'City name, e.g. "Brussels"'
136
+
137
+ def initialize(api_key:, base_url: 'https://api.openweathermap.org')
138
+ super()
139
+ @http = Faraday.new(url: base_url, request: { timeout: 10 })
140
+ @api_key = api_key
584
141
  end
585
-
586
- def handle_api_error(error)
587
- case error
588
- when Faraday::TimeoutError
589
- "API request timed out after #{@timeout} seconds"
590
- when Faraday::ConnectionFailed
591
- "Failed to connect to API: #{error.message}"
592
- else
593
- "API error: #{error.class} - #{error.message}"
594
- end
142
+
143
+ def execute(city:)
144
+ response = @http.get('/data/2.5/weather', { q: city, appid: @api_key, units: 'metric' })
145
+ raise RCrewAI::Tools::ToolError, "Weather API returned #{response.status}" unless response.success?
146
+
147
+ data = JSON.parse(response.body)
148
+ "#{data['name']}: #{data.dig('main', 'temp')}°C, #{data.dig('weather', 0, 'description')}"
595
149
  end
596
150
  end
151
+ ```
597
152
 
598
- # Usage example
599
- github_api = RestApiTool.new(
600
- base_url: 'https://api.github.com',
601
- api_key: ENV['GITHUB_TOKEN'],
602
- auth_type: :header
603
- )
153
+ To use tools that someone else already hosts, connect to an MCP server instead of
154
+ writing a wrapper. See the [MCP guide]({{ site.baseurl }}/mcp).
604
155
 
605
- # Agent can use: USE_TOOL[rest_api](method=get, endpoint=/user/repos, query={per_page: 10})
606
- ```
156
+ ## Errors
607
157
 
608
- ### GraphQL Client Tool
158
+ Raise an error when a tool can't do its job. Under native function calling, the
159
+ exception doesn't fail the task: the model receives `ERROR: <message>` as the tool's
160
+ result and can correct itself. Write messages it can act on:
609
161
 
610
162
  ```ruby
611
- class GraphQLTool < RCrewAI::Tools::Base
612
- def initialize(**options)
613
- super
614
- @name = 'graphql'
615
- @description = 'Execute GraphQL queries and mutations'
616
- @endpoint = options[:endpoint]
617
- @api_key = options[:api_key]
618
- @client = setup_graphql_client
619
- end
620
-
621
- def execute(**params)
622
- validate_params!(params,
623
- required: [:query],
624
- optional: [:variables, :operation_name]
625
- )
626
-
627
- query = params[:query]
628
- variables = params[:variables] || {}
629
- operation_name = params[:operation_name]
630
-
631
- response = @client.execute(
632
- query,
633
- variables: variables,
634
- operation_name: operation_name
635
- )
636
-
637
- format_graphql_response(response)
638
- rescue => e
639
- "GraphQL error: #{e.message}"
640
- end
641
-
642
- private
643
-
644
- def setup_graphql_client
645
- Faraday.new(url: @endpoint) do |f|
646
- f.request :json
647
- f.response :json
648
- f.adapter Faraday.default_adapter
649
-
650
- # Add authentication
651
- f.headers['Authorization'] = "Bearer #{@api_key}" if @api_key
652
- end
653
- end
654
-
655
- def format_graphql_response(response)
656
- if response['errors']
657
- errors = response['errors'].map { |e| e['message'] }.join(', ')
658
- "GraphQL errors: #{errors}"
659
- elsif response['data']
660
- JSON.pretty_generate(response['data'])
661
- else
662
- "Empty response"
163
+ class ReadReport < RCrewAI::Tools::Base
164
+ tool_name 'read_report'
165
+ description 'Read a report by its id'
166
+ param :id, type: :string, required: true
167
+
168
+ REPORTS = { 'q1' => 'Revenue grew 4%.' }.freeze
169
+
170
+ def execute(id:)
171
+ REPORTS.fetch(id) do
172
+ raise RCrewAI::Tools::ToolError, "No report '#{id}'. Available: #{REPORTS.keys.join(', ')}"
663
173
  end
664
174
  end
665
175
  end
666
176
  ```
667
177
 
668
- ## Database Tools
178
+ ## Thread Safety
669
179
 
670
- ### SQL Database Tool
180
+ When a model requests several tools in one turn, they run concurrently on the same
181
+ tool instances. A tool with mutable state must protect it:
671
182
 
672
183
  ```ruby
673
- require 'sequel'
184
+ class Counter < RCrewAI::Tools::Base
185
+ tool_name 'counter'
186
+ description 'Increment a shared counter and return its value'
187
+ param :by, type: :integer, required: true
674
188
 
675
- class SqlDatabaseTool < RCrewAI::Tools::Base
676
- def initialize(**options)
189
+ def initialize
677
190
  super
678
- @name = 'sql_database'
679
- @description = 'Execute SQL queries with safety checks'
680
- @connection_string = options[:connection_string]
681
- @read_only = options[:read_only] || true
682
- @max_rows = options[:max_rows] || 100
683
- @timeout = options[:timeout] || 30
684
-
685
- setup_connection
686
- end
687
-
688
- def execute(**params)
689
- validate_params!(params, required: [:query], optional: [:params])
690
-
691
- query = params[:query]
692
- query_params = params[:params] || []
693
-
694
- # Safety checks
695
- validate_query_safety(query) if @read_only
696
-
697
- # Execute query
698
- result = execute_query(query, query_params)
699
-
700
- # Format result
701
- format_query_result(result)
702
- rescue => e
703
- "Database error: #{e.message}"
704
- end
705
-
706
- private
707
-
708
- def setup_connection
709
- @db = Sequel.connect(@connection_string)
710
- @db.extension :pg_json if @connection_string.include?('postgres')
711
-
712
- # Set connection options
713
- @db.pool.connection_validation_timeout = -1
714
- @db.pool.max_connections = 5
191
+ @count = 0
192
+ @lock = Mutex.new
715
193
  end
716
-
717
- def validate_query_safety(query)
718
- unsafe_keywords = %w[
719
- INSERT UPDATE DELETE DROP CREATE ALTER TRUNCATE
720
- EXEC EXECUTE GRANT REVOKE
721
- ]
722
-
723
- query_upper = query.upcase
724
- unsafe_keywords.each do |keyword|
725
- if query_upper.include?(keyword)
726
- raise ToolError, "Unsafe operation '#{keyword}' not allowed in read-only mode"
727
- end
728
- end
729
- end
730
-
731
- def execute_query(query, params)
732
- Timeout::timeout(@timeout) do
733
- dataset = @db[query, *params]
734
-
735
- # Limit results
736
- dataset = dataset.limit(@max_rows) if dataset.respond_to?(:limit)
737
-
738
- # Execute and fetch
739
- if query.upcase.start_with?('SELECT')
740
- dataset.all
741
- else
742
- rows_affected = dataset
743
- { rows_affected: rows_affected }
744
- end
745
- end
746
- end
747
-
748
- def format_query_result(result)
749
- if result.is_a?(Array)
750
- # Format as table
751
- return "No results" if result.empty?
752
-
753
- headers = result.first.keys
754
- rows = result.map { |r| r.values }
755
-
756
- format_table(headers, rows)
757
- elsif result.is_a?(Hash)
758
- "Query executed: #{result[:rows_affected]} rows affected"
759
- else
760
- result.to_s
761
- end
762
- end
763
-
764
- def format_table(headers, rows)
765
- # Calculate column widths
766
- widths = headers.map(&:to_s).map(&:length)
767
- rows.each do |row|
768
- row.each_with_index do |cell, i|
769
- widths[i] = [widths[i], cell.to_s.length].max
770
- end
771
- end
772
-
773
- # Build table
774
- separator = "+" + widths.map { |w| "-" * (w + 2) }.join("+") + "+"
775
- header_row = "|" + headers.each_with_index.map { |h, i|
776
- " #{h.to_s.ljust(widths[i])} "
777
- }.join("|") + "|"
778
-
779
- table = [separator, header_row, separator]
780
-
781
- rows.each do |row|
782
- row_str = "|" + row.each_with_index.map { |cell, i|
783
- " #{cell.to_s.ljust(widths[i])} "
784
- }.join("|") + "|"
785
- table << row_str
786
- end
787
-
788
- table << separator
789
- table.join("\n")
194
+
195
+ def execute(by:)
196
+ @lock.synchronize { @count += by }.to_s
790
197
  end
791
198
  end
792
199
  ```
793
200
 
794
- ## File Processing Tools
201
+ If that isn't practical, set `parallel_tools: false` on the agent using the tool.
202
+
203
+ ## Security
795
204
 
796
- ### Document Processor Tool
205
+ Treat tool arguments as untrusted input. They come from the model, and the model's
206
+ input may include content from web pages, documents, or users.
797
207
 
798
208
  ```ruby
799
- require 'pdf-reader'
800
- require 'docx'
801
- require 'csv'
802
-
803
- class DocumentProcessorTool < RCrewAI::Tools::Base
804
- SUPPORTED_FORMATS = %w[.pdf .docx .txt .csv .json]
805
-
806
- def initialize(**options)
807
- super
808
- @name = 'document_processor'
809
- @description = 'Extract and process content from various document formats'
810
- @max_file_size = options[:max_file_size] || 10_000_000 # 10MB
811
- end
812
-
813
- def execute(**params)
814
- validate_params!(params,
815
- required: [:file_path],
816
- optional: [:operation, :options]
817
- )
818
-
819
- file_path = params[:file_path]
820
- operation = params[:operation] || :extract_text
821
- options = params[:options] || {}
822
-
823
- # Validate file
824
- validate_file(file_path)
825
-
826
- # Process based on operation
827
- case operation.to_sym
828
- when :extract_text
829
- extract_text(file_path, options)
830
- when :extract_metadata
831
- extract_metadata(file_path)
832
- when :convert
833
- convert_document(file_path, options)
834
- when :analyze
835
- analyze_document(file_path, options)
836
- else
837
- raise ToolError, "Unknown operation: #{operation}"
838
- end
839
- end
840
-
841
- private
842
-
843
- def validate_file(file_path)
844
- unless File.exist?(file_path)
845
- raise ToolError, "File not found: #{file_path}"
846
- end
847
-
848
- if File.size(file_path) > @max_file_size
849
- raise ToolError, "File too large: #{File.size(file_path)} bytes"
850
- end
851
-
852
- ext = File.extname(file_path).downcase
853
- unless SUPPORTED_FORMATS.include?(ext)
854
- raise ToolError, "Unsupported format: #{ext}"
855
- end
856
- end
857
-
858
- def extract_text(file_path, options)
859
- ext = File.extname(file_path).downcase
860
-
861
- text = case ext
862
- when '.pdf'
863
- extract_pdf_text(file_path, options)
864
- when '.docx'
865
- extract_docx_text(file_path)
866
- when '.txt'
867
- File.read(file_path)
868
- when '.csv'
869
- extract_csv_text(file_path, options)
870
- when '.json'
871
- JSON.pretty_generate(JSON.parse(File.read(file_path)))
872
- end
873
-
874
- # Apply options
875
- if options[:max_length]
876
- text = text[0...options[:max_length]]
877
- end
878
-
879
- if options[:clean]
880
- text = clean_text(text)
881
- end
882
-
883
- text
884
- end
885
-
886
- def extract_pdf_text(file_path, options)
887
- reader = PDF::Reader.new(file_path)
888
-
889
- if options[:page]
890
- # Extract specific page
891
- page = reader.pages[options[:page] - 1]
892
- page&.text || ""
893
- else
894
- # Extract all pages
895
- reader.pages.map(&:text).join("\n\n")
896
- end
897
- end
898
-
899
- def extract_docx_text(file_path)
900
- doc = Docx::Document.open(file_path)
901
- doc.paragraphs.map(&:text).join("\n")
902
- end
903
-
904
- def extract_csv_text(file_path, options)
905
- csv_options = {
906
- headers: options[:headers] != false,
907
- encoding: options[:encoding] || 'UTF-8'
908
- }
909
-
910
- rows = CSV.read(file_path, csv_options)
911
-
912
- if options[:as_json]
913
- JSON.pretty_generate(rows.map(&:to_h))
914
- else
915
- CSV.generate do |csv|
916
- rows.each { |row| csv << row }
917
- end
918
- end
919
- end
920
-
921
- def extract_metadata(file_path)
922
- metadata = {
923
- filename: File.basename(file_path),
924
- size: File.size(file_path),
925
- modified: File.mtime(file_path),
926
- format: File.extname(file_path)
927
- }
928
-
929
- ext = File.extname(file_path).downcase
930
-
931
- case ext
932
- when '.pdf'
933
- reader = PDF::Reader.new(file_path)
934
- metadata[:pages] = reader.page_count
935
- metadata[:info] = reader.info
936
- when '.docx'
937
- doc = Docx::Document.open(file_path)
938
- metadata[:paragraphs] = doc.paragraphs.count
939
- metadata[:tables] = doc.tables.count
940
- end
941
-
942
- JSON.pretty_generate(metadata)
943
- end
944
-
945
- def analyze_document(file_path, options)
946
- text = extract_text(file_path, {})
947
-
948
- analysis = {
949
- character_count: text.length,
950
- word_count: text.split.length,
951
- line_count: text.lines.count,
952
- paragraph_count: text.split(/\n\n+/).length
953
- }
954
-
955
- if options[:keywords]
956
- keywords = options[:keywords]
957
- analysis[:keyword_frequency] = {}
958
-
959
- keywords.each do |keyword|
960
- count = text.scan(/#{Regexp.escape(keyword)}/i).length
961
- analysis[:keyword_frequency][keyword] = count
962
- end
963
- end
964
-
965
- JSON.pretty_generate(analysis)
209
+ class ReadDoc < RCrewAI::Tools::Base
210
+ tool_name 'read_doc'
211
+ description 'Read a document from the docs folder'
212
+ param :path, type: :string, required: true, description: 'Path relative to the docs folder'
213
+
214
+ def initialize(root:)
215
+ super()
216
+ @root = File.realpath(root)
966
217
  end
967
-
968
- def clean_text(text)
969
- # Remove extra whitespace
970
- text = text.gsub(/\s+/, ' ')
971
-
972
- # Remove special characters
973
- text = text.gsub(/[^\w\s\.\,\!\?\-]/, '')
974
-
975
- # Normalize line endings
976
- text = text.gsub(/\r\n/, "\n")
977
-
978
- text.strip
218
+
219
+ def execute(path:)
220
+ full = File.realpath(File.join(@root, path))
221
+ raise RCrewAI::Tools::ToolError, 'Path is outside the docs folder' unless full.start_with?("#{@root}/")
222
+
223
+ File.read(full)
224
+ rescue Errno::ENOENT
225
+ raise RCrewAI::Tools::ToolError, "No such document: #{path}"
979
226
  end
980
227
  end
981
228
  ```
982
229
 
983
- ## Testing Custom Tools
230
+ - Resolve paths before checking them, as above, so `../` and symlinks can't escape.
231
+ - Use parameterized queries, and allowlists for commands, hosts, and table names.
232
+ - Keep secrets in `initialize`, and leave them out of return values and error messages.
233
+ - For risky actions, require a person to approve them with `require_approval_for_tools: true`.
234
+
235
+ ## Testing Tools
984
236
 
985
- ### RSpec Tests for Tools
237
+ Test `execute_with_validation` with string keys, since that's how the runner calls
238
+ your tool, with arguments shaped like the model's JSON:
986
239
 
987
240
  ```ruby
988
- require 'rspec'
989
-
990
- RSpec.describe CalculatorTool do
991
- let(:tool) { CalculatorTool.new(precision: 2) }
992
-
993
- describe '#execute' do
994
- context 'with addition' do
995
- it 'adds numbers correctly' do
996
- result = tool.execute(
997
- operation: 'add',
998
- operands: [5, 3, 2]
999
- )
1000
- expect(result).to eq('Result: 10')
1001
- end
1002
- end
1003
-
1004
- context 'with division' do
1005
- it 'divides numbers correctly' do
1006
- result = tool.execute(
1007
- operation: 'divide',
1008
- operands: [10, 2]
1009
- )
1010
- expect(result).to eq('Result: 5')
1011
- end
1012
-
1013
- it 'raises error for division by zero' do
1014
- expect {
1015
- tool.execute(
1016
- operation: 'divide',
1017
- operands: [10, 0]
1018
- )
1019
- }.to raise_error(RCrewAI::Tools::ToolError, /Division by zero/)
1020
- end
1021
- end
1022
-
1023
- context 'with invalid parameters' do
1024
- it 'raises error for missing required parameters' do
1025
- expect {
1026
- tool.execute(operation: 'add')
1027
- }.to raise_error(RCrewAI::Tools::ToolError, /Missing required parameter/)
1028
- end
1029
-
1030
- it 'raises error for invalid operands' do
1031
- expect {
1032
- tool.execute(
1033
- operation: 'add',
1034
- operands: 'not an array'
1035
- )
1036
- }.to raise_error(RCrewAI::Tools::ToolError, /must be an array/)
1037
- end
1038
- end
1039
- end
1040
- end
1041
- ```
241
+ RSpec.describe WordCount do
242
+ subject(:tool) { described_class.new }
1042
243
 
1043
- ### Integration Testing
244
+ it 'counts words' do
245
+ expect(tool.execute_with_validation('text' => 'one two three')).to eq('3')
246
+ end
1044
247
 
1045
- ```ruby
1046
- RSpec.describe 'Tool Integration' do
1047
- let(:agent) do
1048
- RCrewAI::Agent.new(
1049
- name: 'test_agent',
1050
- role: 'Tool Tester',
1051
- goal: 'Test tool integration',
1052
- tools: [
1053
- CalculatorTool.new,
1054
- WeatherTool.new(api_key: 'test_key'),
1055
- SessionMemoryTool.new
1056
- ]
1057
- )
248
+ it 'requires text' do
249
+ expect { tool.execute_with_validation({}) }.to raise_error(RCrewAI::Tools::ToolError, /missing required param/)
1058
250
  end
1059
-
1060
- it 'agent can use multiple tools in sequence' do
1061
- task = RCrewAI::Task.new(
1062
- name: 'complex_calculation',
1063
- description: 'Calculate 5 * 3, store result, then add 10',
1064
- agent: agent
1065
- )
1066
-
1067
- # Mock the reasoning loop to use tools
1068
- allow(agent).to receive(:reasoning_loop) do |task, context|
1069
- # Step 1: Multiply
1070
- result1 = agent.use_tool('calculator',
1071
- operation: 'multiply',
1072
- operands: [5, 3]
1073
- )
1074
-
1075
- # Step 2: Store result
1076
- agent.use_tool('session_memory',
1077
- action: 'store',
1078
- key: 'multiply_result',
1079
- value: 15
1080
- )
1081
-
1082
- # Step 3: Add
1083
- result2 = agent.use_tool('calculator',
1084
- operation: 'add',
1085
- operands: [15, 10]
1086
- )
1087
-
1088
- "Final result: 25"
1089
- end
1090
-
1091
- result = task.execute
1092
- expect(result).to include('25')
251
+
252
+ it 'publishes its schema' do
253
+ expect(described_class.json_schema[:parameters][:required]).to eq(['text'])
1093
254
  end
1094
255
  end
1095
256
  ```
1096
257
 
1097
- ## Tool Security and Validation
258
+ To test an agent using a tool without calling a real API, pass a fake client through
259
+ `llm:`. Anything that responds to `chat` works.
260
+
261
+ ## Tools Without the DSL
1098
262
 
1099
- ### Secure Tool Base Class
263
+ Tools written before the DSL still work:
1100
264
 
1101
265
  ```ruby
1102
- class SecureTool < RCrewAI::Tools::Base
1103
- def execute(**params)
1104
- # Input sanitization
1105
- sanitized_params = sanitize_inputs(params)
1106
-
1107
- # Rate limiting
1108
- check_rate_limit
1109
-
1110
- # Execute with timeout
1111
- Timeout::timeout(execution_timeout) do
1112
- # Audit logging
1113
- log_execution(sanitized_params)
1114
-
1115
- # Execute tool logic
1116
- result = perform_execution(sanitized_params)
1117
-
1118
- # Output validation
1119
- validate_output(result)
1120
-
1121
- result
1122
- end
1123
- rescue Timeout::Error
1124
- handle_timeout
1125
- rescue => e
1126
- handle_error(e)
1127
- end
1128
-
1129
- private
1130
-
1131
- def sanitize_inputs(params)
1132
- params.transform_values do |value|
1133
- case value
1134
- when String
1135
- # Remove potentially dangerous characters
1136
- value.gsub(/[<>'\"&]/, '')
1137
- when Array
1138
- value.map { |v| sanitize_inputs(v) if v.is_a?(String) || v.is_a?(Hash) }
1139
- when Hash
1140
- sanitize_inputs(value)
1141
- else
1142
- value
1143
- end
1144
- end
1145
- end
1146
-
1147
- def check_rate_limit
1148
- @last_execution ||= {}
1149
- key = "#{self.class.name}_#{Thread.current.object_id}"
1150
-
1151
- if @last_execution[key] && Time.now - @last_execution[key] < 1
1152
- raise ToolError, "Rate limit exceeded - please wait"
1153
- end
1154
-
1155
- @last_execution[key] = Time.now
1156
- end
1157
-
1158
- def validate_output(result)
1159
- # Check output size
1160
- if result.to_s.length > 1_000_000
1161
- raise ToolError, "Output too large"
1162
- end
1163
-
1164
- # Check for sensitive data
1165
- if contains_sensitive_data?(result)
1166
- raise ToolError, "Output contains sensitive information"
1167
- end
1168
- end
1169
-
1170
- def contains_sensitive_data?(text)
1171
- patterns = [
1172
- /\b\d{3}-\d{2}-\d{4}\b/, # SSN
1173
- /\b\d{16}\b/, # Credit card
1174
- /api[_-]?key/i, # API keys
1175
- /password/i, # Passwords
1176
- /secret/i # Secrets
1177
- ]
1178
-
1179
- text_str = text.to_s
1180
- patterns.any? { |pattern| text_str.match?(pattern) }
1181
- end
1182
-
1183
- def log_execution(params)
1184
- @logger.info "Tool execution: #{@name}"
1185
- @logger.debug "Parameters: #{params.inspect}"
266
+ class LegacyTool < RCrewAI::Tools::Base
267
+ def initialize
268
+ super
269
+ @name = 'legacy'
270
+ @description = 'A tool that sets its name in initialize'
1186
271
  end
1187
-
1188
- def execution_timeout
1189
- 30 # Default 30 seconds
272
+
273
+ def execute(**params)
274
+ validate_params!(params, required: [:input])
275
+ "Got #{params[:input]}"
1190
276
  end
1191
277
  end
1192
278
  ```
1193
279
 
280
+ A tool like this has no declared parameters, so it prints a warning and gets a
281
+ permissive schema: `Tool LegacyTool has no DSL declarations; using permissive schema`.
282
+ The model then has no description of its arguments, so add `param` declarations when
283
+ you next touch it.
284
+
1194
285
  ## Best Practices
1195
286
 
1196
- ### 1. **Tool Design Principles**
1197
- - Single responsibility - each tool does one thing well
1198
- - Clear, descriptive names and descriptions
1199
- - Comprehensive parameter validation
1200
- - Meaningful error messages
1201
- - Consistent output formatting
1202
-
1203
- ### 2. **Security Considerations**
1204
- - Always sanitize inputs
1205
- - Implement rate limiting
1206
- - Use timeouts to prevent hanging
1207
- - Validate output size and content
1208
- - Audit log all executions
1209
- - Never expose sensitive data
1210
-
1211
- ### 3. **Performance Optimization**
1212
- - Cache expensive operations
1213
- - Use connection pooling for databases/APIs
1214
- - Implement retry logic with backoff
1215
- - Stream large files instead of loading entirely
1216
- - Clean up resources after use
1217
-
1218
- ### 4. **Error Handling**
1219
- - Provide clear error messages
1220
- - Distinguish between recoverable and fatal errors
1221
- - Log errors with context
1222
- - Implement graceful degradation
1223
- - Return partial results when possible
1224
-
1225
- ### 5. **Testing Strategy**
1226
- - Unit test all tool methods
1227
- - Test parameter validation thoroughly
1228
- - Mock external dependencies
1229
- - Test error conditions
1230
- - Integration test with agents
1231
- - Performance test with large inputs
287
+ - **Do one thing per tool.** Several small tools are easier for a model to choose between.
288
+ - **Write descriptions for the model.** Include when to use the tool and what each parameter means.
289
+ - **Return only what's useful.** Tool output goes into the conversation and costs tokens.
290
+ - **Set timeouts on network calls.** A hung tool holds up the whole turn.
291
+ - **Make retried actions safe.** A model may call a tool again after an error.
1232
292
 
1233
293
  ## Next Steps
1234
294
 
1235
- Now that you can build custom tools:
1236
-
1237
- 1. Learn about [Working with Multiple Crews]({{ site.baseurl }}/tutorials/multiple-crews)
1238
- 2. Explore [Production Deployment]({{ site.baseurl }}/tutorials/deployment) strategies
1239
- 3. Review the [Tools API Documentation]({{ site.baseurl }}/api/tools)
1240
- 4. Check out [Example Custom Tools]({{ site.baseurl }}/examples/) in production
1241
-
1242
- Custom tools are essential for extending RCrewAI to handle specialized tasks and integrate with your existing systems.
295
+ - [Tools API reference]({{ site.baseurl }}/api/tools)
296
+ - [Advanced Agent Configuration]({{ site.baseurl }}/tutorials/advanced-agents)
297
+ - [MCP guide]({{ site.baseurl }}/mcp)