@agentforge/core 0.3.8 → 0.3.9

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Tom Van Schoor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(index_exports, {
   ToolMetadataSchema: () => ToolMetadataSchema,
   ToolNameSchema: () => ToolNameSchema,
   ToolRegistry: () => ToolRegistry,
+  ToolRelationsSchema: () => ToolRelationsSchema,
   batch: () => batch,
   broadcast: () => broadcast,
   cache: () => cache,
@@ -177,6 +178,28 @@ var ToolExampleSchema = import_zod.z.object({
    */
   explanation: import_zod.z.string().min(1).optional()
 });
+var ToolRelationsSchema = import_zod.z.object({
+  /**
+   * Tools that must be called before this tool
+   */
+  requires: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  /**
+   * Tools that work well with this tool
+   */
+  suggests: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  /**
+   * Tools that conflict with this tool
+   */
+  conflicts: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  /**
+   * Tools this typically follows in a workflow
+   */
+  follows: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  /**
+   * Tools this typically precedes in a workflow
+   */
+  precedes: import_zod.z.array(import_zod.z.string().min(1)).optional()
+});
 var ToolNameSchema = import_zod.z.string().min(2, "Tool name must be at least 2 characters").max(50, "Tool name must be at most 50 characters").regex(
   /^[a-z][a-z0-9-]*[a-z0-9]$/,
   "Tool name must be kebab-case (lowercase letters, numbers, hyphens only, must start with a letter)"
@@ -235,7 +258,11 @@ var ToolMetadataSchema = import_zod.z.object({
   /**
    * Replacement tool name - if provided, must be valid tool name
    */
-  replacedBy: ToolNameSchema.optional()
+  replacedBy: ToolNameSchema.optional(),
+  /**
+   * Tool relations - defines relationships with other tools
+   */
+  relations: ToolRelationsSchema.optional()
 });
 function validateToolMetadata(metadata) {
   return ToolMetadataSchema.safeParse(metadata);
@@ -544,13 +571,93 @@ var ToolBuilder = class {
   }
   /**
    * Set author (optional)
-   * 
+   *
    * @param author - Tool author name
    */
   author(author) {
     this.metadata.author = author;
     return this;
   }
+  /**
+   * Set tools that must be called before this tool (optional)
+   *
+   * @param tools - Array of tool names that are required
+   * @example
+   * ```ts
+   * .requires(['view-file', 'search-codebase'])
+   * ```
+   */
+  requires(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.requires = tools;
+    return this;
+  }
+  /**
+   * Set tools that work well with this tool (optional)
+   *
+   * @param tools - Array of tool names that are suggested
+   * @example
+   * ```ts
+   * .suggests(['run-tests', 'format-code'])
+   * ```
+   */
+  suggests(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.suggests = tools;
+    return this;
+  }
+  /**
+   * Set tools that conflict with this tool (optional)
+   *
+   * @param tools - Array of tool names that conflict
+   * @example
+   * ```ts
+   * .conflicts(['delete-file'])
+   * ```
+   */
+  conflicts(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.conflicts = tools;
+    return this;
+  }
+  /**
+   * Set tools this typically follows in a workflow (optional)
+   *
+   * @param tools - Array of tool names this follows
+   * @example
+   * ```ts
+   * .follows(['search-codebase', 'view-file'])
+   * ```
+   */
+  follows(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.follows = tools;
+    return this;
+  }
+  /**
+   * Set tools this typically precedes in a workflow (optional)
+   *
+   * @param tools - Array of tool names this precedes
+   * @example
+   * ```ts
+   * .precedes(['run-tests'])
+   * ```
+   */
+  precedes(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.precedes = tools;
+    return this;
+  }
   /**
    * Set the input schema (required)
    * 
@@ -1032,9 +1139,11 @@ var ToolRegistry = class {
       includeExamples = false,
       includeNotes = false,
       includeLimitations = false,
+      includeRelations = false,
       groupByCategory = false,
       categories,
-      maxExamplesPerTool
+      maxExamplesPerTool,
+      minimal = false
     } = options;
     let tools = this.getAll();
     if (categories && categories.length > 0) {
@@ -1060,7 +1169,9 @@ var ToolRegistry = class {
             includeExamples,
             includeNotes,
             includeLimitations,
-            maxExamplesPerTool
+            includeRelations,
+            maxExamplesPerTool,
+            minimal
           }));
         }
         lines.push("");
@@ -1071,7 +1182,9 @@ var ToolRegistry = class {
           includeExamples,
           includeNotes,
           includeLimitations,
-          maxExamplesPerTool
+          includeRelations,
+          maxExamplesPerTool,
+          minimal
         }));
         lines.push("");
       }
@@ -1089,6 +1202,44 @@ var ToolRegistry = class {
   formatToolForPrompt(tool, options) {
     const { metadata } = tool;
     const lines = [];
+    if (options.minimal) {
+      lines.push(`## ${metadata.name}`);
+      let hasContent = false;
+      if (options.includeRelations && metadata.relations) {
+        const relationLines = this.formatRelations(metadata.relations);
+        if (relationLines.length > 0) {
+          lines.push(...relationLines);
+          hasContent = true;
+        }
+      }
+      if (options.includeExamples && metadata.examples && metadata.examples.length > 0) {
+        const maxExamples = options.maxExamplesPerTool || metadata.examples.length;
+        const examples = metadata.examples.slice(0, maxExamples);
+        for (const example of examples) {
+          lines.push(`  Example: ${example.description}`);
+          lines.push(`    Input: ${JSON.stringify(example.input)}`);
+          if (example.explanation) {
+            lines.push(`    ${example.explanation}`);
+          }
+          hasContent = true;
+        }
+      }
+      if (options.includeNotes && metadata.usageNotes) {
+        lines.push(`  Notes: ${metadata.usageNotes}`);
+        hasContent = true;
+      }
+      if (options.includeLimitations && metadata.limitations && metadata.limitations.length > 0) {
+        lines.push(`  Limitations:`);
+        for (const limitation of metadata.limitations) {
+          lines.push(`    - ${limitation}`);
+        }
+        hasContent = true;
+      }
+      if (!hasContent) {
+        return [];
+      }
+      return lines;
+    }
     lines.push(`- ${metadata.name}: ${metadata.description}`);
     const schemaShape = tool.schema._def?.shape?.();
     if (schemaShape) {
@@ -1102,6 +1253,12 @@ var ToolRegistry = class {
         lines.push(`  Parameters: ${paramDescriptions.join(", ")}`);
       }
     }
+    if (options.includeRelations && metadata.relations) {
+      const relationLines = this.formatRelations(metadata.relations);
+      if (relationLines.length > 0) {
+        lines.push(...relationLines);
+      }
+    }
     if (options.includeNotes && metadata.usageNotes) {
       lines.push(`  Notes: ${metadata.usageNotes}`);
     }
@@ -1124,6 +1281,32 @@ var ToolRegistry = class {
     }
     return lines;
   }
+  /**
+   * Format tool relations for inclusion in a prompt
+   *
+   * @param relations - The relations to format
+   * @returns Array of formatted lines
+   * @private
+   */
+  formatRelations(relations) {
+    const lines = [];
+    if (relations.requires && relations.requires.length > 0) {
+      lines.push(`  Requires: ${relations.requires.join(", ")}`);
+    }
+    if (relations.suggests && relations.suggests.length > 0) {
+      lines.push(`  Suggests: ${relations.suggests.join(", ")}`);
+    }
+    if (relations.conflicts && relations.conflicts.length > 0) {
+      lines.push(`  Conflicts: ${relations.conflicts.join(", ")}`);
+    }
+    if (relations.follows && relations.follows.length > 0) {
+      lines.push(`  Follows: ${relations.follows.join(", ")}`);
+    }
+    if (relations.precedes && relations.precedes.length > 0) {
+      lines.push(`  Precedes: ${relations.precedes.join(", ")}`);
+    }
+    return lines;
+  }
 };
 
 // src/tools/executor.ts
@@ -3959,6 +4142,7 @@ function createCircuitBreaker(options) {
   ToolMetadataSchema,
   ToolNameSchema,
   ToolRegistry,
+  ToolRelationsSchema,
   batch,
   broadcast,
   cache,

package/dist/index.d.cts

@@ -100,6 +100,61 @@ interface ToolExample {
      */
     explanation?: string;
 }
+/**
+ * ToolRelations - Defines relationships between tools
+ *
+ * Helps LLMs understand tool workflows and dependencies.
+ *
+ * Why tool relations?
+ * - Express dependencies: "Must call tool X before tool Y"
+ * - Suggest workflows: "After X, consider calling Y"
+ * - Prevent conflicts: "Don't use X and Y together"
+ * - Guide LLM decisions: Better tool selection and ordering
+ *
+ * Example:
+ * ```ts
+ * const relations: ToolRelations = {
+ *   requires: ['view-file'],      // Must call this first
+ *   suggests: ['run-tests'],       // Often used together
+ *   conflicts: ['delete-file'],    // Don't use together
+ *   follows: ['search-codebase'],  // Typically called after
+ *   precedes: ['edit-file']        // Typically called before
+ * };
+ * ```
+ */
+interface ToolRelations {
+    /**
+     * Tools that should be called before this tool
+     *
+     * Example: 'edit-file' requires 'view-file' to be called first
+     * to ensure you know the file contents before editing.
+     */
+    requires?: string[];
+    /**
+     * Tools that work well with this tool
+     *
+     * Example: 'edit-file' suggests 'run-tests' to verify changes.
+     */
+    suggests?: string[];
+    /**
+     * Tools that conflict with this tool
+     *
+     * Example: 'create-file' conflicts with 'delete-file' on the same path.
+     */
+    conflicts?: string[];
+    /**
+     * Tools this typically follows in a workflow
+     *
+     * Example: 'edit-file' typically follows 'view-file' or 'search-codebase'.
+     */
+    follows?: string[];
+    /**
+     * Tools this typically precedes in a workflow
+     *
+     * Example: 'view-file' typically precedes 'edit-file'.
+     */
+    precedes?: string[];
+}
 /**
  * ToolMetadata - Rich metadata for a tool
  *
@@ -193,6 +248,25 @@ interface ToolMetadata {
      * Example: 'read-file-v2'
      */
     replacedBy?: string;
+    /**
+     * Tool relations (optional)
+     * Defines relationships with other tools
+     *
+     * Helps LLMs understand:
+     * - Which tools should be called before/after this tool
+     * - Which tools work well together
+     * - Which tools conflict with this tool
+     *
+     * Example:
+     * ```ts
+     * relations: {
+     *   requires: ['view-file'],
+     *   suggests: ['run-tests'],
+     *   follows: ['search-codebase']
+     * }
+     * ```
+     */
+    relations?: ToolRelations;
 }
 /**
  * Tool - Complete tool definition
@@ -314,6 +388,57 @@ declare const ToolExampleSchema: z.ZodObject<{
     output?: unknown;
     explanation?: string | undefined;
 }>;
+/**
+ * Schema for ToolRelations
+ *
+ * Validates tool relationship definitions.
+ * All fields are optional arrays of tool names.
+ *
+ * Example:
+ * ```ts
+ * ToolRelationsSchema.parse({
+ *   requires: ['view-file'],
+ *   suggests: ['run-tests', 'format-code'],
+ *   conflicts: ['delete-file'],
+ *   follows: ['search-codebase'],
+ *   precedes: ['run-tests']
+ * });
+ * ```
+ */
+declare const ToolRelationsSchema: z.ZodObject<{
+    /**
+     * Tools that must be called before this tool
+     */
+    requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools that work well with this tool
+     */
+    suggests: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools that conflict with this tool
+     */
+    conflicts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools this typically follows in a workflow
+     */
+    follows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools this typically precedes in a workflow
+     */
+    precedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    requires?: string[] | undefined;
+    suggests?: string[] | undefined;
+    conflicts?: string[] | undefined;
+    follows?: string[] | undefined;
+    precedes?: string[] | undefined;
+}, {
+    requires?: string[] | undefined;
+    suggests?: string[] | undefined;
+    conflicts?: string[] | undefined;
+    follows?: string[] | undefined;
+    precedes?: string[] | undefined;
+}>;
 /**
  * Schema for tool names
  *
@@ -420,6 +545,43 @@ declare const ToolMetadataSchema: z.ZodObject<{
      * Replacement tool name - if provided, must be valid tool name
      */
     replacedBy: z.ZodOptional<z.ZodString>;
+    /**
+     * Tool relations - defines relationships with other tools
+     */
+    relations: z.ZodOptional<z.ZodObject<{
+        /**
+         * Tools that must be called before this tool
+         */
+        requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools that work well with this tool
+         */
+        suggests: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools that conflict with this tool
+         */
+        conflicts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools this typically follows in a workflow
+         */
+        follows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools this typically precedes in a workflow
+         */
+        precedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    }, {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     description: string;
     name: string;
@@ -438,6 +600,13 @@ declare const ToolMetadataSchema: z.ZodObject<{
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }, {
     description: string;
     name: string;
@@ -456,6 +625,13 @@ declare const ToolMetadataSchema: z.ZodObject<{
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Helper function to validate tool metadata
@@ -496,6 +672,13 @@ declare function validateToolMetadata(metadata: unknown): z.SafeParseReturnType<
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }, {
     description: string;
     name: string;
@@ -514,6 +697,13 @@ declare function validateToolMetadata(metadata: unknown): z.SafeParseReturnType<
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Helper function to validate tool name
@@ -802,6 +992,56 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
      * @param author - Tool author name
      */
     author(author: string): this;
+    /**
+     * Set tools that must be called before this tool (optional)
+     *
+     * @param tools - Array of tool names that are required
+     * @example
+     * ```ts
+     * .requires(['view-file', 'search-codebase'])
+     * ```
+     */
+    requires(tools: string[]): this;
+    /**
+     * Set tools that work well with this tool (optional)
+     *
+     * @param tools - Array of tool names that are suggested
+     * @example
+     * ```ts
+     * .suggests(['run-tests', 'format-code'])
+     * ```
+     */
+    suggests(tools: string[]): this;
+    /**
+     * Set tools that conflict with this tool (optional)
+     *
+     * @param tools - Array of tool names that conflict
+     * @example
+     * ```ts
+     * .conflicts(['delete-file'])
+     * ```
+     */
+    conflicts(tools: string[]): this;
+    /**
+     * Set tools this typically follows in a workflow (optional)
+     *
+     * @param tools - Array of tool names this follows
+     * @example
+     * ```ts
+     * .follows(['search-codebase', 'view-file'])
+     * ```
+     */
+    follows(tools: string[]): this;
+    /**
+     * Set tools this typically precedes in a workflow (optional)
+     *
+     * @param tools - Array of tool names this precedes
+     * @example
+     * ```ts
+     * .precedes(['run-tests'])
+     * ```
+     */
+    precedes(tools: string[]): this;
     /**
      * Set the input schema (required)
      *
@@ -886,12 +1126,29 @@ interface PromptOptions {
     includeNotes?: boolean;
     /** Include limitations in the prompt */
     includeLimitations?: boolean;
+    /** Include tool relations in the prompt */
+    includeRelations?: boolean;
     /** Group tools by category */
     groupByCategory?: boolean;
     /** Filter by specific categories */
     categories?: ToolCategory[];
     /** Maximum number of examples to include per tool */
     maxExamplesPerTool?: number;
+    /**
+     * Minimal mode - only supplementary context, not full definitions
+     *
+     * Use this when tool definitions are sent via API (OpenAI, Anthropic, etc.)
+     *
+     * When true:
+     * - Excludes basic tool name/description/parameters
+     * - Includes only relations, examples, notes, limitations
+     * - Tool names are used as headers for matching
+     *
+     * When false (default):
+     * - Includes full tool definitions (current behavior)
+     * - Backward compatible
+     */
+    minimal?: boolean;
 }
 /**
  * Tool Registry - Central registry for managing tools
@@ -1182,6 +1439,14 @@ declare class ToolRegistry {
      * @private
      */
     private formatToolForPrompt;
+    /**
+     * Format tool relations for inclusion in a prompt
+     *
+     * @param relations - The relations to format
+     * @returns Array of formatted lines
+     * @private
+     */
+    private formatRelations;
 }
 
 /**
@@ -4073,4 +4338,4 @@ declare class CircuitBreaker {
 }
 declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export { AgentError, type AggregateNode, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type ExecutionMetrics, type HealthCheckConfig, type HealthCheckResult, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type ReducerFunction, RegistryEvent, type RequestConfig, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolSimulatorConfig, type TracingOptions, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getToolDescription, getToolJsonSchema, isMemoryCheckpointer, isTracingEnabled, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, retry, safeValidateSchemaDescriptions, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withErrorHandler, withMetrics, withRetry, withTimeout, withTracing };
+export { AgentError, type AggregateNode, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type ExecutionMetrics, type HealthCheckConfig, type HealthCheckResult, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type ReducerFunction, RegistryEvent, type RequestConfig, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getToolDescription, getToolJsonSchema, isMemoryCheckpointer, isTracingEnabled, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, retry, safeValidateSchemaDescriptions, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withErrorHandler, withMetrics, withRetry, withTimeout, withTracing };

package/dist/index.d.ts

@@ -100,6 +100,61 @@ interface ToolExample {
      */
     explanation?: string;
 }
+/**
+ * ToolRelations - Defines relationships between tools
+ *
+ * Helps LLMs understand tool workflows and dependencies.
+ *
+ * Why tool relations?
+ * - Express dependencies: "Must call tool X before tool Y"
+ * - Suggest workflows: "After X, consider calling Y"
+ * - Prevent conflicts: "Don't use X and Y together"
+ * - Guide LLM decisions: Better tool selection and ordering
+ *
+ * Example:
+ * ```ts
+ * const relations: ToolRelations = {
+ *   requires: ['view-file'],      // Must call this first
+ *   suggests: ['run-tests'],       // Often used together
+ *   conflicts: ['delete-file'],    // Don't use together
+ *   follows: ['search-codebase'],  // Typically called after
+ *   precedes: ['edit-file']        // Typically called before
+ * };
+ * ```
+ */
+interface ToolRelations {
+    /**
+     * Tools that should be called before this tool
+     *
+     * Example: 'edit-file' requires 'view-file' to be called first
+     * to ensure you know the file contents before editing.
+     */
+    requires?: string[];
+    /**
+     * Tools that work well with this tool
+     *
+     * Example: 'edit-file' suggests 'run-tests' to verify changes.
+     */
+    suggests?: string[];
+    /**
+     * Tools that conflict with this tool
+     *
+     * Example: 'create-file' conflicts with 'delete-file' on the same path.
+     */
+    conflicts?: string[];
+    /**
+     * Tools this typically follows in a workflow
+     *
+     * Example: 'edit-file' typically follows 'view-file' or 'search-codebase'.
+     */
+    follows?: string[];
+    /**
+     * Tools this typically precedes in a workflow
+     *
+     * Example: 'view-file' typically precedes 'edit-file'.
+     */
+    precedes?: string[];
+}
 /**
  * ToolMetadata - Rich metadata for a tool
  *
@@ -193,6 +248,25 @@ interface ToolMetadata {
      * Example: 'read-file-v2'
      */
     replacedBy?: string;
+    /**
+     * Tool relations (optional)
+     * Defines relationships with other tools
+     *
+     * Helps LLMs understand:
+     * - Which tools should be called before/after this tool
+     * - Which tools work well together
+     * - Which tools conflict with this tool
+     *
+     * Example:
+     * ```ts
+     * relations: {
+     *   requires: ['view-file'],
+     *   suggests: ['run-tests'],
+     *   follows: ['search-codebase']
+     * }
+     * ```
+     */
+    relations?: ToolRelations;
 }
 /**
  * Tool - Complete tool definition
@@ -314,6 +388,57 @@ declare const ToolExampleSchema: z.ZodObject<{
     output?: unknown;
     explanation?: string | undefined;
 }>;
+/**
+ * Schema for ToolRelations
+ *
+ * Validates tool relationship definitions.
+ * All fields are optional arrays of tool names.
+ *
+ * Example:
+ * ```ts
+ * ToolRelationsSchema.parse({
+ *   requires: ['view-file'],
+ *   suggests: ['run-tests', 'format-code'],
+ *   conflicts: ['delete-file'],
+ *   follows: ['search-codebase'],
+ *   precedes: ['run-tests']
+ * });
+ * ```
+ */
+declare const ToolRelationsSchema: z.ZodObject<{
+    /**
+     * Tools that must be called before this tool
+     */
+    requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools that work well with this tool
+     */
+    suggests: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools that conflict with this tool
+     */
+    conflicts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools this typically follows in a workflow
+     */
+    follows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Tools this typically precedes in a workflow
+     */
+    precedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    requires?: string[] | undefined;
+    suggests?: string[] | undefined;
+    conflicts?: string[] | undefined;
+    follows?: string[] | undefined;
+    precedes?: string[] | undefined;
+}, {
+    requires?: string[] | undefined;
+    suggests?: string[] | undefined;
+    conflicts?: string[] | undefined;
+    follows?: string[] | undefined;
+    precedes?: string[] | undefined;
+}>;
 /**
  * Schema for tool names
  *
@@ -420,6 +545,43 @@ declare const ToolMetadataSchema: z.ZodObject<{
      * Replacement tool name - if provided, must be valid tool name
      */
     replacedBy: z.ZodOptional<z.ZodString>;
+    /**
+     * Tool relations - defines relationships with other tools
+     */
+    relations: z.ZodOptional<z.ZodObject<{
+        /**
+         * Tools that must be called before this tool
+         */
+        requires: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools that work well with this tool
+         */
+        suggests: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools that conflict with this tool
+         */
+        conflicts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools this typically follows in a workflow
+         */
+        follows: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Tools this typically precedes in a workflow
+         */
+        precedes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    }, {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     description: string;
     name: string;
@@ -438,6 +600,13 @@ declare const ToolMetadataSchema: z.ZodObject<{
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }, {
     description: string;
     name: string;
@@ -456,6 +625,13 @@ declare const ToolMetadataSchema: z.ZodObject<{
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Helper function to validate tool metadata
@@ -496,6 +672,13 @@ declare function validateToolMetadata(metadata: unknown): z.SafeParseReturnType<
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }, {
     description: string;
     name: string;
@@ -514,6 +697,13 @@ declare function validateToolMetadata(metadata: unknown): z.SafeParseReturnType<
     author?: string | undefined;
     deprecated?: boolean | undefined;
     replacedBy?: string | undefined;
+    relations?: {
+        requires?: string[] | undefined;
+        suggests?: string[] | undefined;
+        conflicts?: string[] | undefined;
+        follows?: string[] | undefined;
+        precedes?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Helper function to validate tool name
@@ -802,6 +992,56 @@ declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
      * @param author - Tool author name
      */
     author(author: string): this;
+    /**
+     * Set tools that must be called before this tool (optional)
+     *
+     * @param tools - Array of tool names that are required
+     * @example
+     * ```ts
+     * .requires(['view-file', 'search-codebase'])
+     * ```
+     */
+    requires(tools: string[]): this;
+    /**
+     * Set tools that work well with this tool (optional)
+     *
+     * @param tools - Array of tool names that are suggested
+     * @example
+     * ```ts
+     * .suggests(['run-tests', 'format-code'])
+     * ```
+     */
+    suggests(tools: string[]): this;
+    /**
+     * Set tools that conflict with this tool (optional)
+     *
+     * @param tools - Array of tool names that conflict
+     * @example
+     * ```ts
+     * .conflicts(['delete-file'])
+     * ```
+     */
+    conflicts(tools: string[]): this;
+    /**
+     * Set tools this typically follows in a workflow (optional)
+     *
+     * @param tools - Array of tool names this follows
+     * @example
+     * ```ts
+     * .follows(['search-codebase', 'view-file'])
+     * ```
+     */
+    follows(tools: string[]): this;
+    /**
+     * Set tools this typically precedes in a workflow (optional)
+     *
+     * @param tools - Array of tool names this precedes
+     * @example
+     * ```ts
+     * .precedes(['run-tests'])
+     * ```
+     */
+    precedes(tools: string[]): this;
     /**
      * Set the input schema (required)
      *
@@ -886,12 +1126,29 @@ interface PromptOptions {
     includeNotes?: boolean;
     /** Include limitations in the prompt */
     includeLimitations?: boolean;
+    /** Include tool relations in the prompt */
+    includeRelations?: boolean;
     /** Group tools by category */
     groupByCategory?: boolean;
     /** Filter by specific categories */
     categories?: ToolCategory[];
     /** Maximum number of examples to include per tool */
     maxExamplesPerTool?: number;
+    /**
+     * Minimal mode - only supplementary context, not full definitions
+     *
+     * Use this when tool definitions are sent via API (OpenAI, Anthropic, etc.)
+     *
+     * When true:
+     * - Excludes basic tool name/description/parameters
+     * - Includes only relations, examples, notes, limitations
+     * - Tool names are used as headers for matching
+     *
+     * When false (default):
+     * - Includes full tool definitions (current behavior)
+     * - Backward compatible
+     */
+    minimal?: boolean;
 }
 /**
  * Tool Registry - Central registry for managing tools
@@ -1182,6 +1439,14 @@ declare class ToolRegistry {
      * @private
      */
     private formatToolForPrompt;
+    /**
+     * Format tool relations for inclusion in a prompt
+     *
+     * @param relations - The relations to format
+     * @returns Array of formatted lines
+     * @private
+     */
+    private formatRelations;
 }
 
 /**
@@ -4073,4 +4338,4 @@ declare class CircuitBreaker {
 }
 declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export { AgentError, type AggregateNode, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type ExecutionMetrics, type HealthCheckConfig, type HealthCheckResult, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type ReducerFunction, RegistryEvent, type RequestConfig, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolSimulatorConfig, type TracingOptions, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getToolDescription, getToolJsonSchema, isMemoryCheckpointer, isTracingEnabled, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, retry, safeValidateSchemaDescriptions, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withErrorHandler, withMetrics, withRetry, withTimeout, withTracing };
+export { AgentError, type AggregateNode, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type ExecutionMetrics, type HealthCheckConfig, type HealthCheckResult, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type ReducerFunction, RegistryEvent, type RequestConfig, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getToolDescription, getToolJsonSchema, isMemoryCheckpointer, isTracingEnabled, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, retry, safeValidateSchemaDescriptions, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withErrorHandler, withMetrics, withRetry, withTimeout, withTracing };

package/dist/index.js

@@ -35,6 +35,28 @@ var ToolExampleSchema = z.object({
    */
   explanation: z.string().min(1).optional()
 });
+var ToolRelationsSchema = z.object({
+  /**
+   * Tools that must be called before this tool
+   */
+  requires: z.array(z.string().min(1)).optional(),
+  /**
+   * Tools that work well with this tool
+   */
+  suggests: z.array(z.string().min(1)).optional(),
+  /**
+   * Tools that conflict with this tool
+   */
+  conflicts: z.array(z.string().min(1)).optional(),
+  /**
+   * Tools this typically follows in a workflow
+   */
+  follows: z.array(z.string().min(1)).optional(),
+  /**
+   * Tools this typically precedes in a workflow
+   */
+  precedes: z.array(z.string().min(1)).optional()
+});
 var ToolNameSchema = z.string().min(2, "Tool name must be at least 2 characters").max(50, "Tool name must be at most 50 characters").regex(
   /^[a-z][a-z0-9-]*[a-z0-9]$/,
   "Tool name must be kebab-case (lowercase letters, numbers, hyphens only, must start with a letter)"
@@ -93,7 +115,11 @@ var ToolMetadataSchema = z.object({
   /**
    * Replacement tool name - if provided, must be valid tool name
    */
-  replacedBy: ToolNameSchema.optional()
+  replacedBy: ToolNameSchema.optional(),
+  /**
+   * Tool relations - defines relationships with other tools
+   */
+  relations: ToolRelationsSchema.optional()
 });
 function validateToolMetadata(metadata) {
   return ToolMetadataSchema.safeParse(metadata);
@@ -402,13 +428,93 @@ var ToolBuilder = class {
   }
   /**
    * Set author (optional)
-   * 
+   *
    * @param author - Tool author name
    */
   author(author) {
     this.metadata.author = author;
     return this;
   }
+  /**
+   * Set tools that must be called before this tool (optional)
+   *
+   * @param tools - Array of tool names that are required
+   * @example
+   * ```ts
+   * .requires(['view-file', 'search-codebase'])
+   * ```
+   */
+  requires(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.requires = tools;
+    return this;
+  }
+  /**
+   * Set tools that work well with this tool (optional)
+   *
+   * @param tools - Array of tool names that are suggested
+   * @example
+   * ```ts
+   * .suggests(['run-tests', 'format-code'])
+   * ```
+   */
+  suggests(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.suggests = tools;
+    return this;
+  }
+  /**
+   * Set tools that conflict with this tool (optional)
+   *
+   * @param tools - Array of tool names that conflict
+   * @example
+   * ```ts
+   * .conflicts(['delete-file'])
+   * ```
+   */
+  conflicts(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.conflicts = tools;
+    return this;
+  }
+  /**
+   * Set tools this typically follows in a workflow (optional)
+   *
+   * @param tools - Array of tool names this follows
+   * @example
+   * ```ts
+   * .follows(['search-codebase', 'view-file'])
+   * ```
+   */
+  follows(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.follows = tools;
+    return this;
+  }
+  /**
+   * Set tools this typically precedes in a workflow (optional)
+   *
+   * @param tools - Array of tool names this precedes
+   * @example
+   * ```ts
+   * .precedes(['run-tests'])
+   * ```
+   */
+  precedes(tools) {
+    if (!this.metadata.relations) {
+      this.metadata.relations = {};
+    }
+    this.metadata.relations.precedes = tools;
+    return this;
+  }
   /**
    * Set the input schema (required)
    * 
@@ -890,9 +996,11 @@ var ToolRegistry = class {
       includeExamples = false,
       includeNotes = false,
       includeLimitations = false,
+      includeRelations = false,
       groupByCategory = false,
       categories,
-      maxExamplesPerTool
+      maxExamplesPerTool,
+      minimal = false
     } = options;
     let tools = this.getAll();
     if (categories && categories.length > 0) {
@@ -918,7 +1026,9 @@ var ToolRegistry = class {
             includeExamples,
             includeNotes,
             includeLimitations,
-            maxExamplesPerTool
+            includeRelations,
+            maxExamplesPerTool,
+            minimal
           }));
         }
         lines.push("");
@@ -929,7 +1039,9 @@ var ToolRegistry = class {
           includeExamples,
           includeNotes,
           includeLimitations,
-          maxExamplesPerTool
+          includeRelations,
+          maxExamplesPerTool,
+          minimal
         }));
         lines.push("");
       }
@@ -947,6 +1059,44 @@ var ToolRegistry = class {
   formatToolForPrompt(tool, options) {
     const { metadata } = tool;
     const lines = [];
+    if (options.minimal) {
+      lines.push(`## ${metadata.name}`);
+      let hasContent = false;
+      if (options.includeRelations && metadata.relations) {
+        const relationLines = this.formatRelations(metadata.relations);
+        if (relationLines.length > 0) {
+          lines.push(...relationLines);
+          hasContent = true;
+        }
+      }
+      if (options.includeExamples && metadata.examples && metadata.examples.length > 0) {
+        const maxExamples = options.maxExamplesPerTool || metadata.examples.length;
+        const examples = metadata.examples.slice(0, maxExamples);
+        for (const example of examples) {
+          lines.push(`  Example: ${example.description}`);
+          lines.push(`    Input: ${JSON.stringify(example.input)}`);
+          if (example.explanation) {
+            lines.push(`    ${example.explanation}`);
+          }
+          hasContent = true;
+        }
+      }
+      if (options.includeNotes && metadata.usageNotes) {
+        lines.push(`  Notes: ${metadata.usageNotes}`);
+        hasContent = true;
+      }
+      if (options.includeLimitations && metadata.limitations && metadata.limitations.length > 0) {
+        lines.push(`  Limitations:`);
+        for (const limitation of metadata.limitations) {
+          lines.push(`    - ${limitation}`);
+        }
+        hasContent = true;
+      }
+      if (!hasContent) {
+        return [];
+      }
+      return lines;
+    }
     lines.push(`- ${metadata.name}: ${metadata.description}`);
     const schemaShape = tool.schema._def?.shape?.();
     if (schemaShape) {
@@ -960,6 +1110,12 @@ var ToolRegistry = class {
         lines.push(`  Parameters: ${paramDescriptions.join(", ")}`);
       }
     }
+    if (options.includeRelations && metadata.relations) {
+      const relationLines = this.formatRelations(metadata.relations);
+      if (relationLines.length > 0) {
+        lines.push(...relationLines);
+      }
+    }
     if (options.includeNotes && metadata.usageNotes) {
       lines.push(`  Notes: ${metadata.usageNotes}`);
     }
@@ -982,6 +1138,32 @@ var ToolRegistry = class {
     }
     return lines;
   }
+  /**
+   * Format tool relations for inclusion in a prompt
+   *
+   * @param relations - The relations to format
+   * @returns Array of formatted lines
+   * @private
+   */
+  formatRelations(relations) {
+    const lines = [];
+    if (relations.requires && relations.requires.length > 0) {
+      lines.push(`  Requires: ${relations.requires.join(", ")}`);
+    }
+    if (relations.suggests && relations.suggests.length > 0) {
+      lines.push(`  Suggests: ${relations.suggests.join(", ")}`);
+    }
+    if (relations.conflicts && relations.conflicts.length > 0) {
+      lines.push(`  Conflicts: ${relations.conflicts.join(", ")}`);
+    }
+    if (relations.follows && relations.follows.length > 0) {
+      lines.push(`  Follows: ${relations.follows.join(", ")}`);
+    }
+    if (relations.precedes && relations.precedes.length > 0) {
+      lines.push(`  Precedes: ${relations.precedes.join(", ")}`);
+    }
+    return lines;
+  }
 };
 
 // src/tools/executor.ts
@@ -3816,6 +3998,7 @@ export {
   ToolMetadataSchema,
   ToolNameSchema,
   ToolRegistry,
+  ToolRelationsSchema,
   batch,
   broadcast,
   cache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Core abstractions for AgentForge - production-ready deep agents framework",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -16,17 +16,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "clean": "rm -rf dist *.tsbuildinfo"
-  },
   "keywords": [
     "agents",
     "ai",
@@ -64,5 +53,16 @@
   },
   "dependencies": {
     "zod-to-json-schema": "^3.25.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "rm -rf dist *.tsbuildinfo"
   }
-}
+}