Tools API

execute(toolName: string, options: ExecuteToolOptions): Promise<ExecutionResult>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const execution = await eyeball.tools.execute("gmail.create_draft", {
  userId: "user_42",
  input: { to: ["guest@example.com"], subject: "Review", body: "Draft" },
  idempotencyKey: "draft:reservation:42",
});

get<Format extends EyeballToolFormat = "canonical">(options?: GetToolsOptions<Format>): Promise<GetToolsResult<Format>>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const bundle = await eyeball.tools.get({
  toolkits: ["gmail"],
  format: "anthropic",
});
console.log(bundle.tools, bundle.nameMap);

run(toolName: string, input: unknown, options?: RunToolOptions): Promise<JsonValue>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const output = await eyeball.tools.run(
  "gmail.search_emails",
  { query: "reservation", pageSize: 5 },
  { userId: "user_42", timeoutMs: 30_000 },
);

search(options: SearchToolsOptions): Promise<SearchToolsResult>

executeToolCalls(eyeball: Eyeball, calls: readonly AnthropicToolCall[], options: ExecuteToolCallsOptions): Promise<AnthropicToolResultBlock[]>

executeToolCalls(eyeball: Eyeball, calls: readonly OpenAIToolCall[], options: ExecuteToolCallsOptions): Promise<OpenAIToolResultMessage[]>

export interface SearchToolsOptions {
  query: string;
  limit?: number;
  /** Optional local catalog filters, applied before ranking. */
  toolkits?: readonly string[];
  capability?: CapabilitySlug;
  /** Accepted for parity with the future hosted project-scoped search surface. */
  userId?: string;
}

export interface SearchToolsResult {
  tools: readonly ToolDefinition[];
}

export interface GetToolsOptions<
  Format extends EyeballToolFormat = "canonical",
> {
  /**
   * Binds framework-owned execute callbacks to an end user. Tool discovery itself is
   * resolved entirely from the local `@eyeball/catalog`; hosted project catalog policy
   * belongs to eyeball-cloud and is not fetched by this method.
   */
  userId?: string;
  toolkits?: readonly string[];
  capability?: CapabilitySlug;
  format?: Format;
  /** MCP only: include async-by-nature tools after Tasks support is negotiated. */
  includeAsync?: boolean;
}

export interface GetToolsResult<Format extends EyeballToolFormat> {
  tools: EyeballToolFormatMap[Format];
  nameMap: ToolNameMap;
  raw: readonly ToolDefinition[];
}

export type EyeballToolFormat =
  | "canonical"
  | "anthropic"
  | "openai"
  | "ai-sdk"
  | "mcp";

export interface EyeballToolFormatMap {
  canonical: readonly ToolDefinition[];
  anthropic: AnthropicToolDescriptor[];
  openai: OpenAIFunctionToolDescriptor[];
  "ai-sdk": AiSdkToolSet;
  mcp: McpToolDescriptor[];
}

export interface ExecuteToolOptions {
  /** Uses the client-level userId when omitted. */
  userId?: string;
  input: Readonly<Record<string, JsonValue>>;
  /** Defaults from the canonical tool's `annotations.async` value. */
  mode?: ExecutionMode;
  /**
   * Stable caller key for retry correlation. When omitted for a mutation, the SDK
   * generates a fresh `crypto.randomUUID()` for this invocation. Pass your own key
   * when separate calls must replay the same execution.
   */
  idempotencyKey?: string;
  connectionId?: ConnectionId;
}

export interface RunToolOptions
  extends Omit<ExecuteToolOptions, "input">,
    WaitForExecutionOptions {}

export interface ExecuteToolCallsOptions {
  /** Exact map emitted with the model-facing tool bundle. Unmapped calls are rejected. */
  nameMap: ToolNameMap;
  /** Uses the client-level userId when omitted. */
  userId?: string;
  connectionId?: ConnectionId;
  mode?: ExecutionMode;
  pollMs?: number;
  timeoutMs?: number;
}

export interface AnthropicToolCall {
  type: "tool_use";
  id: string;
  name: string;
  input: unknown;
}

export interface AnthropicToolResultBlock {
  type: "tool_result";
  tool_use_id: string;
  content: string;
  is_error?: boolean;
}

export interface OpenAIFunctionToolCall {
  id: string;
  type: "function";
  function: {
    name: string;
    arguments: string | Readonly<Record<string, JsonValue>>;
  };
}

export interface OpenAICustomToolCall {
  id: string;
  type: "custom";
  custom: { name: string; input: string };
}

export type OpenAIToolCall = OpenAIFunctionToolCall | OpenAICustomToolCall;

export interface OpenAIToolResultMessage {
  role: "tool";
  tool_call_id: string;
  content: string;
}

export type QualifiedToolName = `${string}.${string}`;

export interface ToolDefinition {
  /** Exactly `<toolkit>.<canonical-tool>`, for example `gmail.send_email`. */
  name: QualifiedToolName;
  toolkit: ToolkitSlug;
  capability: CapabilitySlug;
  /** LLM-facing purpose, selection guidance, exclusions, and consequences. */
  description: string;
  inputSchema: ObjectSchema202012;
  outputSchema?: ObjectSchema202012;
  annotations: ToolAnnotations;
  version: SemVer;
}

export interface ToolNameMap {
  canonicalToWire: Readonly<Record<QualifiedToolName, string>>;
  wireToCanonical: Readonly<Record<string, QualifiedToolName>>;
}