Common External Tools - Smithers

API reference: Tools lists every built-in tool and helper, its options, and links to source and tests.

For each external service, you have three choices:

OpenAPI tools: point createOpenApiTools() at the service’s OpenAPI spec. See OpenAPI tools.
CLI in a task: if the service has a CLI (gh, linear, notion, slack), run it inside a <Task> via the bash tool. See side-effect tools with idempotency.
Custom defineTool: wrap the service’s REST API in a Zod-validated tool. See defineTool.

Example: CLI in a task (Pattern 2)

<Task
  id="open-pr"
  tools={[bash]}
  prompt="Run: gh pr create --title 'Fix login bug' --body 'Closes #42'"
/>

Run gh auth login once on the host before executing. The bash tool executes in the task’s sandbox, so credentials set in the environment carry through automatically.

Quick decision

Service	Recommended approach
GitHub	`gh` CLI in a task (auth via `gh auth login`)
Linear	`linear` CLI in a task, or OpenAPI tools
Notion	OpenAPI tools (Notion publishes a spec)
Slack	OpenAPI tools or `slack` CLI
Obsidian	`bash` tool with vault path; no API needed

Always mark side-effecting tools with sideEffect: true and use ctx.idempotencyKey so retries don’t double-fire.