> ## Documentation Index
> Fetch the complete documentation index at: https://smithers-feat-claude-workflow-mirror.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Common External Tools

> 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 theme={null}
<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.