docs(tools): document public API

.changeset/doc03-tools.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/tools': patch
+---
+
+Document the public API.

docs/stability/jsdoc-coverage-v1.json

@@ -1120,20 +1120,6 @@
       ".::validateToolTemplate"
     ],
     "@agentskit/tools": [
-      ".::DefineZodToolConfig",
-      ".::FetchUrlConfig",
-      ".::filesystem",
-      ".::FilesystemConfig",
-      ".::listTools",
-      ".::shell",
-      ".::ShellConfig",
-      ".::slackTool",
-      ".::SlackToolConfig",
-      ".::SqliteQueryConfig",
-      ".::sqliteQueryTool",
-      ".::WebSearchConfig",
-      ".::WebSearchProvider",
-      ".::WebSearchResult",
       "./integrations::browserAgent",
       "./integrations::BrowserAgentConfig",
       "./integrations::browserClick",

packages/tools/src/discovery.ts

@@ -5,6 +5,7 @@ import { fetchUrl } from './fetch-url'
 import { filesystem } from './filesystem'
 import { shell } from './shell'
 
+/** Model-facing metadata for one built-in tool. */
 export interface ToolMetadata {
   name: string
   description: string
@@ -23,6 +24,10 @@ function extractMetadata(tool: ToolDefinition): ToolMetadata {
   }
 }
 
+/** List metadata for the package's built-in tools using their default configurations.
+ *
+ * @returns Names, descriptions, tags, categories, and JSON Schemas for each built-in tool.
+ */
 export function listTools(): ToolMetadata[] {
   // Instantiate tools with safe defaults to extract their metadata
   const tools: ToolDefinition[] = [

packages/tools/src/fetch-url.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from '@agentskit/core'
 import { checkEgress } from './safe-fetch'
 
+/** Response, redirect, and egress settings for {@link fetchUrl}. */
 export interface FetchUrlConfig {
   /** Maximum bytes to read from the response body. Default: 200 KB. */
   maxBytes?: number
@@ -82,6 +83,15 @@ function stripHtml(html: string): string {
  * - Caps response size via `maxBytes` so a huge page can't flood the
  *   model's context window or blow memory.
  * - Strips HTML tags by default; set `raw: true` to get the body verbatim.
+ *
+ * @param config Byte cap, timeout, user agent, and egress policy options.
+ * @returns A `fetch_url` tool definition.
+ * @example
+ * ```ts
+ * import { fetchUrl } from '@agentskit/tools'
+ *
+ * const tool = fetchUrl({ maxBytes: 100_000 })
+ * ```
  */
 export function fetchUrl(config: FetchUrlConfig = {}): ToolDefinition {
   const {

packages/tools/src/filesystem.ts

@@ -2,6 +2,7 @@ import { isAbsolute, resolve, relative, sep } from 'node:path'
 import { ErrorCodes, ToolError } from '@agentskit/core'
 import type { ToolDefinition } from '@agentskit/core'
 
+/** Workspace root and symlink policy for {@link filesystem}. */
 export interface FilesystemConfig {
   basePath: string
   /**
@@ -115,6 +116,17 @@ async function realJailPath(
   return real
 }
 
+/** Create jailed file read, write, and directory-listing tools.
+ *
+ * @param config Workspace root and symlink policy.
+ * @returns The `read_file`, confirmation-gated `write_file`, and `list_directory` tools.
+ * @example
+ * ```ts
+ * import { filesystem } from '@agentskit/tools'
+ *
+ * const tools = filesystem({ basePath: './workspace' })
+ * ```
+ */
 export function filesystem(config: FilesystemConfig): ToolDefinition[] {
   const basePath = resolve(config.basePath)
   const denySymlinks = config.denySymlinks ?? true

packages/tools/src/shell.ts

@@ -1,6 +1,7 @@
 import { ConfigError, ErrorCodes, type ToolDefinition } from '@agentskit/core'
 import { isWindows } from '@agentskit/cross-platform/pure'
 
+/** Executable allowlist, timeout, output cap, working directory, and environment for {@link shell}. */
 export interface ShellConfig {
   /** Per-command timeout in ms. Default 30s. */
   timeout?: number
@@ -51,6 +52,18 @@ function parseCommand(input: string, windows: boolean): { argv: string[]; reason
   return { argv }
 }
 
+/** Create a confirmation-gated tool that runs one executable without a shell.
+ *
+ * @param config Allowlist or trusted open mode, timeout, output limit, and process options.
+ * @returns A `shell` tool definition.
+ * @throws {ConfigError} With code AK_CONFIG_INVALID when neither `allowed` nor `allowAny` is set.
+ * @example
+ * ```ts
+ * import { shell } from '@agentskit/tools'
+ *
+ * const tool = shell({ allowed: ['git', 'node'] })
+ * ```
+ */
 export function shell(config: ShellConfig = {}): ToolDefinition {
   const {
     timeout = 30_000,

packages/tools/src/slack.ts

@@ -5,6 +5,7 @@ import type { ToolDefinition } from '@agentskit/core'
 
 const MAX_SLACK_ERROR_BYTES = 1024
 
+/** Incoming webhook and request cancellation settings for {@link slackTool}. */
 export interface SlackToolConfig {
   webhookUrl: string
   /** Override fetch (mainly for tests). Defaults to the global `fetch`. */
@@ -13,6 +14,19 @@ export interface SlackToolConfig {
   signal?: AbortSignal
 }
 
+/** Create a confirmation-gated tool that sends messages through a Slack webhook.
+ *
+ * @param config Slack incoming webhook URL and optional fetch, timeout, and abort signal.
+ * @returns A `slack_send` tool definition.
+ * @throws {ConfigError} With code AK_CONFIG_INVALID when `webhookUrl` is empty.
+ * @throws {ToolError} During execution when the message is empty or Slack returns a non-success response.
+ * @example
+ * ```ts
+ * import { slackTool } from '@agentskit/tools'
+ *
+ * const tool = slackTool({ webhookUrl: process.env.SLACK_WEBHOOK_URL! })
+ * ```
+ */
 export function slackTool(config: SlackToolConfig): ToolDefinition {
   if (!config.webhookUrl) {
     throw new ConfigError({

packages/tools/src/sqlite-query.ts

@@ -1,6 +1,7 @@
 import { ConfigError, ErrorCodes, ToolError } from '@agentskit/core'
 import type { ToolDefinition } from '@agentskit/core'
 
+/** Read-only database path and row limit for {@link sqliteQueryTool}. */
 export interface SqliteQueryConfig {
   path: string
   /** Reserved for v2; only `true` is accepted today. */
@@ -39,6 +40,19 @@ async function openDatabase(path: string): Promise<SqliteDb> {
 
 const WRITE_KEYWORDS = /\b(?:insert|update|delete|drop|create|alter|attach|detach|replace|reindex|vacuum|pragma)\b/i
 
+/** Create a read-only SQLite query tool backed by optional `better-sqlite3`.
+ *
+ * @param config Database file path, read-only flag, and maximum returned rows.
+ * @returns A `sqlite_query` tool definition.
+ * @throws {ConfigError} With code AK_CONFIG_INVALID for an unsupported `readOnly` value or invalid `maxRows`.
+ * @throws {ToolError} During execution when `better-sqlite3` is unavailable or the query is not read-only.
+ * @example
+ * ```ts
+ * import { sqliteQueryTool } from '@agentskit/tools'
+ *
+ * const tool = sqliteQueryTool({ path: './data.db', maxRows: 50 })
+ * ```
+ */
 export function sqliteQueryTool(config: SqliteQueryConfig): ToolDefinition {
   if (config.readOnly !== undefined && config.readOnly !== true) {
     throw new ConfigError({

packages/tools/src/web-search.ts

@@ -3,14 +3,17 @@ import { NetError, NetErrorCodes, readText } from '@agentskit/net'
 import type { ToolDefinition } from '@agentskit/core'
 import { safeFetch } from './safe-fetch'
 
+/** Title, URL, and text snippet returned by a web-search provider. */
 export interface WebSearchResult {
   title: string
   url: string
   snippet: string
 }
 
+/** Search backend selection; `auto` prefers configured Serper, then Tavily, then DuckDuckGo. */
 export type WebSearchProvider = 'auto' | 'serper' | 'tavily' | 'duckduckgo'
 
+/** Provider, credentials, result count, timeout, response cap, and custom search settings for {@link webSearch}. */
 export interface WebSearchConfig {
   /**
    * Which backend to use. `'auto'` (default) picks the best available:

packages/tools/src/zod.ts

@@ -18,6 +18,7 @@ type InferZodOutput<T> = T extends ZodLike<infer O> ? O : never
 // defineZodTool — Zod-based tool definition with automatic type inference
 // ---------------------------------------------------------------------------
 
+/** Configuration for {@link defineZodTool}, including its runtime and JSON Schema adapters. */
 export interface DefineZodToolConfig<TSchema extends ZodLike> {
   name: string
   description?: string
@@ -46,6 +47,8 @@ export interface DefineZodToolConfig<TSchema extends ZodLike> {
  * callback lets you convert the Zod schema to JSON Schema for the adapter
  * (e.g. using `zod-to-json-schema`).
  *
+ * @param config Tool metadata, Zod schema, and optional schema-conversion and execution callbacks.
+ * @returns A `ToolDefinition` whose execution arguments are inferred from the schema.
  * @example
  * ```ts
  * import { z } from 'zod'