---
title: Common External Tools
description: Patterns for hitting GitHub, Linear, Notion, Slack, Obsidian as tools.
---

<Note>API reference: [Tools](/reference/tools) lists every built-in tool and helper, its options, and links to source and tests.</Note>

For each external service, you have three choices:

1. **OpenAPI tools**: point `createOpenApiTools()` at the service's OpenAPI spec. See [OpenAPI tools](/concepts/openapi-tools).
2. **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](/recipes#side-effect-tools-with-idempotency).
3. **Custom `defineTool`**: wrap the service's REST API in a Zod-validated tool. See [`defineTool`](/integrations/tools#definetool).

### Example: CLI in a task (Pattern 2)

```tsx
<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.
