utils/tool_search/tool_search_utils library
Tool Search utilities for dynamically discovering deferred tools.
When enabled, deferred tools (MCP and shouldDefer tools) are sent with defer_loading: true and discovered via ToolSearchTool rather than being loaded upfront.
Also includes tool error formatting, tool pool management, and tool schema caching.
Classes
- AgentDefinition
- Represents an agent definition for tool search context.
- CachedToolSchema
- Cached tool schema entry.
- DeferredToolsDelta
- Represents changes to the deferred tool pool.
- DeferredToolsDeltaScanContext
- Context for deferred tools delta scanning.
- MissingParamIssue
- A required parameter is missing.
- ToolDefinition
- Represents a tool definition with metadata for search and filtering.
- ToolPermissionContext
- Context for tool permission checks.
- ToolSchemaCache
- Session-scoped cache of rendered tool schemas.
- ToolSearchController
- Controller for tool search state and operations.
- ToolSearchMessage
- Minimal message representation for tool reference extraction.
- TypeMismatchIssue
- A parameter has an incorrect type.
- UnexpectedParamIssue
- An unexpected parameter was provided.
- ValidationIssue
- Validation issue types for structured error formatting.
Enums
- DeferredToolsDeltaScanCallSite
- Call-site discriminator for delta scan events.
- InstallStatus
- Status of a tool installation or pool operation.
- ToolSearchMode
- Tool search mode. Determines how deferrable tools (MCP + shouldDefer) are surfaced:
Constants
- interruptMessageForToolUse → const String
- Name used for the interrupt sentinel.
- toolSearchToolName → const String
- Tool search tool name constant.
- toolTokenCountOverhead → const int
- Token count overhead for tool definitions.
Properties
- toolSchemaCache → ToolSchemaCache
-
Global tool schema cache instance.
final
Functions
-
applyCoordinatorToolFilter(
{required List< ToolDefinition> tools, required Set<String> coordinatorAllowedTools}) → List<ToolDefinition> - Filters a tool list to the set allowed in coordinator mode.
-
clearToolSchemaCache(
) → void - Clear the global tool schema cache.
-
formatError(
Object error) → String - Formats an error into a human-readable string, with truncation for very long messages.
-
formatValidationError(
{required String toolName, required List< ValidationIssue> issues, String? fallbackMessage}) → String - Converts validation errors into a human-readable and LLM-friendly error message.
-
formatValidationPath(
List path) → String -
Formats a validation path into a readable string.
e.g.,
'todos', 0, 'activeForm'=> 'todos0.activeForm' -
getErrorParts(
Object error) → List< String> - Extracts error parts from a structured error.
-
isPrActivitySubscriptionTool(
String name) → bool - Check if a tool name is a PR activity subscription tool.
-
mergeAndFilterTools(
{required List< ToolDefinition> initialTools, required List<ToolDefinition> assembled, required String mode, bool isCoordinatorMode = false, Set<String> ? coordinatorAllowedTools}) → List<ToolDefinition> - Pure function that merges tool pools and applies coordinator mode filtering.
Exceptions / Errors
- AbortError
- Custom error for user-initiated aborts.
- ShellError
- Custom error for shell command failures.