# Tools reference

Source: https://social9.com/docs/ai-apps/tools-reference

> Every tool a connected AI app can use in Social9, what each one does, and the permission it needs.

These are the actions an AI app can take in Social9. You never call them yourself: you ask in plain words, and the app picks the tool.

An app only sees the tools its permissions allow. See [Permissions and practice mode](https://social9.com/docs/ai-apps/permissions-and-practice-mode).

---

## Reading your workspace

Permission: **See your brands and calendar**.

| Tool | What it does |
|---|---|
| `whoami` | Shows the workspace, who is signed in, the plan, the brands it can use, what it may do, the timezone, and whether practice mode is on |
| `list_brands` | Lists the brands it can use, with their connected accounts |
| `get_brand_profile` | Reads a brand's voice, audience, offer, topics and words to avoid |
| `list_channels` | Lists connected accounts and whether any need reconnecting |
| `list_posts` | Finds posts by status, date or text |
| `get_calendar` | Shows what is planned and posted, day by day, including empty days |
| `list_approvals` | Lists posts waiting in Approvals, with any flags |
| `get_analytics` | Shows posts and their likes, comments, shares and clicks, for as many days back as your plan allows |
| `get_usage` | Shows your plan, what is left this month, and what each AI action costs |
| `get_best_times` | Suggests the next good times to post, skipping times that already have a post |
| `weekly_review` | Sums up the last 7 days and the next 7: what went out, what failed, what needs you |
| `get_brand_voice` | Reads a brand's full voice settings and facts sheet |
| `brand_voice_check` | Checks a post for avoided words, length limits, hashtags and links. Can also rewrite it in your voice (4 credits) |

---

## Brands

| Tool | What it does |
|---|---|
| `create_brand` | Creates a new brand with every detail you give it (website, description, audience, voice, offerings, hashtags, content pillars…). Counts toward your plan's brand limit. You then connect its accounts on the Channels page |
| `update_brand` | Fills in or changes any brand detail. Send only what changes |

---

## Posts

Permission: **Create and schedule posts**, unless it says otherwise.

| Tool | What it does |
|---|---|
| `create_post` | Saves a new post as a draft |
| `update_post` | Changes a post that has not gone out yet |
| `schedule_post` | Puts a post on the calendar at a time you agree, or the next good time. Can send it to Approvals instead |
| `bulk_schedule` | Schedules several drafts at once, each at its own good time |
| `duplicate_post` | Copies a post into a new draft |
| `delete_post` | Deletes a draft or scheduled post. Posted posts cannot be deleted |
| `publish_now` | Posts right away. Also needs **Publish posts right away** |
| `approve_post` | Approves a post waiting in Approvals. Needs **Approve or reject posts** |
| `reject_post` | Sends a post back to drafts with a reason. Needs **Approve or reject posts** |

---

## Your own photos, videos and posts

Permission: **Create and schedule posts**, unless it says otherwise.

| Tool | What it does |
|---|---|
| `upload_media_from_url` | Copies an image or video from a public link into your media library |
| `create_upload_url` | Gives the app a private link to upload a file you have |
| `finish_upload` | Confirms an upload landed, and resumes a large one if parts are missing |
| `caption_media` | Writes a caption in your brand voice for each file, with facts to check. Needs **Use your AI credits** (4 credits per caption) |
| `schedule_existing_media` | Makes one post per file, as drafts, scheduled or for approval |
| `import_posts` | Creates up to 200 posts in one go, from a list. Can check them first without creating anything |

---

## Writing with AI

Permission: **Use your AI credits**. These use the same credits as the dashboard. A post costs 4 credits.

| Tool | What it does |
|---|---|
| `suggest_what_to_post` | Looks at your empty days, topics and recent posts, and suggests ideas with a day and time. Saves nothing (4 credits) |
| `generate_posts` | Writes posts about a topic for one or more networks, saved as drafts |
| `plan_posts` | Plans a week, 2 weeks or a month of posts from a link or a description. Also needs **Create and schedule posts** |
| `fill_calendar_gaps` | Finds empty slots on each account and writes drafts for them, up to 30 at a time. Also needs **Create and schedule posts** |
| `adapt_for_networks` | Turns one message into a version for each network (4 credits per network) |
| `repurpose_link` | Reads a web page and writes one post per network about it (4 credits per network) |
| `generate_ideas` | Writes post ideas and saves them to the brand's Ideas (4 credits per batch) |
| `generate_image` | Makes an image in your brand's style and saves it to your media library (10 credits, 20 for sharper) |

AI tools save drafts unless you ask for more. If credits run short, `plan_posts` writes as many as your credits allow.

---

## Brand voice

| Tool | What it does | Permission |
|---|---|---|
| `update_brand_voice` | Changes a brand's voice settings, after checking with you. Not available in practice mode | **Edit brand voice** |

---

## Help docs

These need no permission.

| Tool | What it does |
|---|---|
| `search_docs` | Searches these help docs, so the app can answer "how do I…" questions from them |
| `read_doc` | Reads one help docs page, so the app can guide you step by step and give you the link |

---

## Ready-made prompts

Some apps show these as shortcuts:

| Prompt | What it does |
|---|---|
| **plan_my_week** | Looks at the calendar, finds the gaps and plans this week's posts as drafts |
| **turn_link_into_posts** | Reads a page and writes one post per connected network, saved as drafts |

---

## Limits

- Plan limits and credits are the same as in the dashboard. When a limit is hit, the app gets a plain message and an upgrade link. Limits are checked before anything changes. When scheduling many posts at once, it stops at the limit and keeps the rest as drafts.
- Each connection can make up to 120 requests a minute, and up to 20 AI requests a minute.

---

## Next steps

- [Permissions and practice mode](https://social9.com/docs/ai-apps/permissions-and-practice-mode)
- [Credits and usage](https://social9.com/docs/account/credits-and-usage)