DependsOn (Topological Sort)

Tools can declare dependsOn — a list of other tool names that must execute before them. When multiple tool calls are scheduled in a round, the runtime topologically sorts them so dependencies always run first.

Declaring dependencies

typescript

export const summariseTool: ToolDefinition = {
  name: 'summarise_results',
  description: 'Summarise search results into a report',
  dependsOn: ['search', 'fetch_page'],  // these run first
  parameters: z.object({ topic: z.string() }),
  execute: async ({ topic }, ctx) => {
    // By the time this runs, search and fetch_page results
    // are already in the tool result context
    return await summarise(topic, ctx)
  },
}

How the sort works

typescript

// Simplified topological sort used by the runtime
function topoSortToolCalls(calls) {
  const visited = new Set()
  const result = []

  function visit(call) {
    if (visited.has(call.id)) return
    visited.add(call.id)
    const tool = tools.get(call.name)
    for (const dep of tool?.dependsOn ?? []) {
      const depCall = calls.find(c => c.name === dep)
      if (depCall) visit(depCall)  // dependency executes first
    }
    result.push(call)
  }

  for (const call of calls) visit(call)
  return result
}

Rules

Circular dependencies are not detected at sort time — avoid them
If a declared dependency is not called in the same round, the sort skips it
Works alongside batchable tools and async dispatch

dependsOn expresses ordering intent, not data passing. Use the shared ctx.sessionId to read prior tool results from the session if you need actual output from a dependency.