mirror of
https://github.com/simstudioai/sim.git
synced 2026-10-29 18:23:56 +08:00
feat(docs): fill documentation gaps across platform features (#4110)
* feat(docs): fill documentation gaps across platform features
* fix(docs): address PR review comments on chat OTP cookies and MCP env var placeholders
* fix(docs): replace smart quotes with straight quotes in JSX attributes
* update(docs): update mcp, custom tools, and variables docs
* Fix grammar
* mothership docs, tags, connectors, api, chat deploy, etc
* more info
* more
* feat(docs): auto-generate per-provider trigger documentation
Extends scripts/generate-docs.ts to produce one MDX page per trigger
provider (39 pages) in apps/docs/content/docs/en/triggers/. The 5
hand-written pages (index, start, schedule, webhook, rss) are never
touched.
Key additions to the generation script:
- resolveConstVariable() resolves module-level const spreads so
providers like Vercel that build outputs from const variables (not
just functions) are fully documented
- resolveTriggerBuilderFunction() extended to expand variable spreads
(...varName) in addition to function-call spreads (...fn())
- groupTriggersByProvider() deduplicates v1/v2 trigger variants by
name, keeping the highest-versioned one per provider
- writeIconMapping() adds bare-name aliases for versioned block types
(github_v2 → github, fireflies_v2 → fireflies, etc.) so
BlockInfoCard resolves icons for all 39 trigger providers
- extractTriggerConfigFields() filters readOnly display blocks (webhook
URL displays, sample payloads, curl examples) from config tables
Each generated page includes: BlockInfoCard with correct icon/color,
trigger count, polling note where applicable, Configuration table, and
Output table for every trigger. No "Type:" lines.
* refactor(docs): align trigger docs structure with tools docs
- Use ### `trigger_id` headings (matching ### `tool_id` in tools docs)
- Wrap all trigger sections under a ## Triggers header
- Rename Configuration/Output to #### level (matching #### Input/Output)
- Use Parameter column header to match tools docs table style
- Map UI widget types to semantic types: short-input/long-input/dropdown
→ string, switch → boolean, slider → number, oauth-input → string
* refactor(docs): use human-readable names for trigger section headings
Trigger IDs are internal identifiers; users scan by name. Switch from
### `trigger_id` to ### Trigger Name for cleaner sidebar navigation
and better readability.
* fix(docs): resolve subBlock builder functions for all trigger Config sections
Extends generate-docs.ts to parse subBlock builder functions so all 15
providers previously missing Configuration sections now generate them.
Handles three patterns:
- `buildTriggerSubBlocks({extraFields: buildX(...)})` — extracts extra
fields from the call site and resolves them from the provider's utils.ts
- `return [...]` — direct array return (Attio, Confluence, etc.)
- `blocks.push(...)` — imperative push pattern (Linear, Ashby)
Also resolves const-reference field IDs (SCREAMING_CASE) by searching
the webhook provider constants cache, fixing Gong's `gongJwtPublicKeyPem`
field which was previously unresolvable. Adds title-as-description fallback
for OAuth credential fields that have no explicit description.
* fix(docs): correctly destructure nested implicit-object trigger outputs
Fixes a parser bug where output fields with no top-level `type` key but
child fields each having their own `type`/`description` were incorrectly
parsed. The `type:` and `description:` regex matches were not
depth-aware, so values from nested children bled into the parent field.
Changes:
- Add `isAtDepthZero()` helper for brace-depth-aware regex matching
- Fix `parseFieldContent` to only match `type:` at brace depth 0
- Fix `extractDescription` to only match `description:` at brace depth 0
- Add implicit-object fallback: when no top-level `type` exists but child
fields have their own types, treat as `object` with `properties`
- Regenerate all affected trigger docs (Cal.com payload, Linear data,
Jira issue.fields, Ashby application, Greenhouse candidate, etc.)
* chore(docs): update static trigger and start page images
* feat(providers): add claude-opus-4-7 model with adaptive thinking support
* Add workflow version screenshots
* Add function block screenshots
---------
Co-authored-by: Theodore Li <theo@sim.ai>
This commit is contained in:
Waleed
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Custom Tools
|
||||
description: Create your own tools with JavaScript code and use them in Agent blocks
|
||||
---
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout'
|
||||
import { Step, Steps } from 'fumadocs-ui/components/steps'
|
||||
import { FAQ } from '@/components/ui/faq'
|
||||
|
||||
Custom tools let you write your own JavaScript functions and make them available as callable tools in Agent blocks. This is useful when you need functionality that isn't covered by Sim's built-in integrations — for example, calling an internal API, performing a custom calculation, or transforming data in a specific way.
|
||||
|
||||
## How Custom Tools Work
|
||||
|
||||
A custom tool has two parts:
|
||||
|
||||
1. **Schema** — A JSON definition describing the tool's name, description, and parameters (using the OpenAI function-calling format). This tells the AI agent what the tool does and what inputs it expects.
|
||||
2. **Code** — A JavaScript function body that runs when the agent calls the tool. Parameters defined in the schema are available as variables in your code.
|
||||
|
||||
When an Agent block has access to a custom tool, the AI model decides when to call it based on the schema description and the conversation context — just like built-in tools.
|
||||
|
||||
## Creating a Custom Tool
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
|
||||
### Open Custom Tools settings
|
||||
|
||||
Navigate to **Settings → Custom Tools** in your workspace and click **Add**.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Define the schema
|
||||
|
||||
In the **Schema** tab, define your tool using JSON in the OpenAI function-calling format:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "get_weather",
|
||||
"description": "Get the current weather for a city",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"description": "The city name"
|
||||
},
|
||||
"units": {
|
||||
"type": "string",
|
||||
"enum": ["celsius", "fahrenheit"],
|
||||
"description": "Temperature units"
|
||||
}
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
You can use the AI wand button to generate a schema from a natural language description of what the tool should do.
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Write the code
|
||||
|
||||
Switch to the **Code** tab and write the JavaScript function body. Parameters from your schema are available directly as variables:
|
||||
|
||||
```javascript
|
||||
const response = await fetch(
|
||||
`https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units === 'celsius' ? 'metric' : 'imperial'}&appid={{OPENWEATHER_API_KEY}}`
|
||||
);
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
return {
|
||||
temperature: data.main.temp,
|
||||
description: data.weather[0].description,
|
||||
humidity: data.main.humidity
|
||||
};
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
You can also use the AI wand to generate code from a description. Environment variables are referenced with `{{KEY}}` syntax.
|
||||
</Callout>
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### Save
|
||||
|
||||
Click **Save** to create the tool. It's now available to use in any Agent block across your workspace.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Using Custom Tools in Workflows
|
||||
|
||||
Once created, custom tools appear alongside built-in tools when configuring an Agent block:
|
||||
|
||||
1. Open an Agent block
|
||||
2. Click **Add Tools**
|
||||
3. Find your custom tool in the tool list
|
||||
4. The agent will call the tool when it determines it's relevant to the task
|
||||
|
||||
## Code Environment
|
||||
|
||||
### Available Features
|
||||
|
||||
- **Async/await** — Your code runs in an async context, so you can use `await` directly
|
||||
- **fetch()** — Make HTTP requests to external APIs
|
||||
- **Node.js built-ins** — Access to `crypto`, `Buffer`, and other standard modules
|
||||
- **Environment variables** — Use `{{KEY}}` syntax to inject secrets
|
||||
|
||||
### Limitations
|
||||
|
||||
- **No npm packages** — External libraries like `axios` or `lodash` are not available. Use built-in APIs instead
|
||||
- **Parameters by name** — Schema parameters are available directly as variables (e.g., `city`), not via a `params` object
|
||||
|
||||
### Returning Results
|
||||
|
||||
Return a value from your code to send it back to the agent:
|
||||
|
||||
```javascript
|
||||
const result = await fetch(`https://api.example.com/data?q=${query}`);
|
||||
const data = await result.json();
|
||||
return data;
|
||||
```
|
||||
|
||||
The returned value becomes the tool output that the agent sees and can use in its response.
|
||||
|
||||
## Managing Custom Tools
|
||||
|
||||
From **Settings → Custom Tools** you can:
|
||||
|
||||
- **Search** tools by name, function name, or description
|
||||
- **Edit** any tool's schema or code
|
||||
- **Delete** tools that are no longer needed
|
||||
|
||||
<Callout type="warn">
|
||||
Deleting a custom tool removes it from all Agent blocks that reference it. Make sure no active workflows depend on the tool before deleting.
|
||||
</Callout>
|
||||
|
||||
## Permissions
|
||||
|
||||
| Action | Required Permission |
|
||||
|--------|-------------------|
|
||||
| View custom tools | **Read**, **Write**, or **Admin** |
|
||||
| Create or edit tools | **Write** or **Admin** |
|
||||
| Delete tools | **Write** or **Admin** |
|
||||
|
||||
<FAQ items={[
|
||||
{ question: "Can I use custom tools in standalone blocks (not agents)?", answer: "No. Custom tools are designed for use within Agent blocks, where the AI model decides when to call them. For deterministic tool execution, use the Function block instead." },
|
||||
{ question: "How do I pass API keys to my custom tool code?", answer: "Use environment variables with double curly brace syntax: {{MY_API_KEY}}. Create the environment variable in Settings → Secrets, and it will be injected at execution time without appearing in logs." },
|
||||
{ question: "Can I use external npm packages?", answer: "No. Custom tool code runs in a sandboxed environment with access to built-in Node.js modules and fetch(), but not external packages. For complex dependencies, consider calling an external API that wraps the functionality you need." },
|
||||
{ question: "What's the difference between custom tools and the Function block?", answer: "Custom tools are called by AI agents when they decide the tool is relevant — the agent chooses when to use it. Function blocks run deterministically at a fixed point in the workflow. Use custom tools for agent-driven actions and Function blocks for predictable data transformations." },
|
||||
{ question: "Are custom tools shared across the workspace?", answer: "Yes. Custom tools are workspace-scoped, so all workspace members can use them in their workflows." },
|
||||
]} />
|
||||
@@ -409,7 +409,7 @@ Retrieve interaction statistics for users by date range from Gong. Only includes
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ---- | ----------- |
|
||||
| `peopleInteractionStats` | array | Email address of the Gong user |
|
||||
| `peopleInteractionStats` | array | Interaction statistics per user. Applicable stat names: 'Longest Monologue', 'Longest Customer Story', 'Interactivity', 'Patience', 'Question Rate'. |
|
||||
| ↳ `userId` | string | Gong's unique numeric identifier for the user |
|
||||
| ↳ `userEmailAddress` | string | Email address of the Gong user |
|
||||
| ↳ `personInteractionStats` | array | List of interaction stat measurements for this user |
|
||||
@@ -656,7 +656,7 @@ Retrieve coaching metrics for a manager from Gong.
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ---- | ----------- |
|
||||
| `requestId` | string | A Gong request reference ID for troubleshooting purposes |
|
||||
| `coachingData` | array | The manager user information |
|
||||
| `coachingData` | array | A list of coaching data entries, one per manager's team |
|
||||
| ↳ `manager` | object | The manager user information |
|
||||
| ↳ `id` | string | Gong unique numeric identifier for the user |
|
||||
| ↳ `emailAddress` | string | Email address of the Gong user |
|
||||
|
||||
@@ -31,6 +31,7 @@
|
||||
"confluence",
|
||||
"crowdstrike",
|
||||
"cursor",
|
||||
"custom-tools",
|
||||
"dagster",
|
||||
"databricks",
|
||||
"datadog",
|
||||
|
||||
@@ -87,7 +87,7 @@ Read a specific page from a SharePoint site
|
||||
| ↳ `createdDateTime` | string | When the page was created |
|
||||
| ↳ `lastModifiedDateTime` | string | When the page was last modified |
|
||||
| `pages` | array | List of SharePoint pages |
|
||||
| ↳ `page` | object | The unique ID of the page |
|
||||
| ↳ `page` | object | page output from the tool |
|
||||
| ↳ `id` | string | The unique ID of the page |
|
||||
| ↳ `name` | string | The name of the page |
|
||||
| ↳ `title` | string | The title of the page |
|
||||
@@ -95,7 +95,7 @@ Read a specific page from a SharePoint site
|
||||
| ↳ `pageLayout` | string | The layout type of the page |
|
||||
| ↳ `createdDateTime` | string | When the page was created |
|
||||
| ↳ `lastModifiedDateTime` | string | When the page was last modified |
|
||||
| ↳ `content` | object | Extracted text content from the page |
|
||||
| ↳ `content` | object | content output from the tool |
|
||||
| ↳ `content` | string | Extracted text content from the page |
|
||||
| ↳ `canvasLayout` | object | Raw SharePoint canvas layout structure |
|
||||
| `content` | object | Content of the SharePoint page |
|
||||
@@ -127,9 +127,9 @@ List details of all SharePoint sites
|
||||
| ↳ `createdDateTime` | string | When the site was created |
|
||||
| ↳ `lastModifiedDateTime` | string | When the site was last modified |
|
||||
| ↳ `isPersonalSite` | boolean | Whether this is a personal site |
|
||||
| ↳ `root` | object | Server relative URL |
|
||||
| ↳ `root` | object | root output from the tool |
|
||||
| ↳ `serverRelativeUrl` | string | Server relative URL |
|
||||
| ↳ `siteCollection` | object | Site collection hostname |
|
||||
| ↳ `siteCollection` | object | siteCollection output from the tool |
|
||||
| ↳ `hostname` | string | Site collection hostname |
|
||||
| `sites` | array | List of all accessible SharePoint sites |
|
||||
| ↳ `id` | string | The unique ID of the site |
|
||||
|
||||
@@ -66,7 +66,7 @@ Integrate AWS Textract into your workflow to extract text, tables, forms, and ke
|
||||
| ↳ `Confidence` | number | Confidence score \(0-100\) |
|
||||
| ↳ `Page` | number | Page number |
|
||||
| ↳ `Geometry` | object | Location and bounding box information |
|
||||
| ↳ `BoundingBox` | object | Height as ratio of document height |
|
||||
| ↳ `BoundingBox` | object | BoundingBox output from the tool |
|
||||
| ↳ `Height` | number | Height as ratio of document height |
|
||||
| ↳ `Left` | number | Left position as ratio of document width |
|
||||
| ↳ `Top` | number | Top position as ratio of document height |
|
||||
|
||||
@@ -96,7 +96,7 @@ Retrieve insights and analytics for Typeform forms
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ---- | ----------- |
|
||||
| `fields` | array | Number of users who dropped off at this field |
|
||||
| `fields` | array | Analytics data for individual form fields |
|
||||
| ↳ `dropoffs` | number | Number of users who dropped off at this field |
|
||||
| ↳ `id` | string | Unique field ID |
|
||||
| ↳ `label` | string | Field label |
|
||||
@@ -104,15 +104,15 @@ Retrieve insights and analytics for Typeform forms
|
||||
| ↳ `title` | string | Field title/question |
|
||||
| ↳ `type` | string | Field type \(e.g., short_text, multiple_choice\) |
|
||||
| ↳ `views` | number | Number of times this field was viewed |
|
||||
| `form` | object | Average completion time for this platform |
|
||||
| ↳ `platforms` | array | Average completion time for this platform |
|
||||
| `form` | object | Form-level analytics and performance data |
|
||||
| ↳ `platforms` | array | Platform-specific analytics data |
|
||||
| ↳ `average_time` | number | Average completion time for this platform |
|
||||
| ↳ `completion_rate` | number | Completion rate for this platform |
|
||||
| ↳ `platform` | string | Platform name \(e.g., desktop, mobile\) |
|
||||
| ↳ `responses_count` | number | Number of responses from this platform |
|
||||
| ↳ `total_visits` | number | Total visits from this platform |
|
||||
| ↳ `unique_visits` | number | Unique visits from this platform |
|
||||
| ↳ `summary` | object | Overall average completion time |
|
||||
| ↳ `summary` | object | Overall form performance summary |
|
||||
| ↳ `average_time` | number | Overall average completion time |
|
||||
| ↳ `completion_rate` | number | Overall completion rate |
|
||||
| ↳ `responses_count` | number | Total number of responses |
|
||||
|
||||
Reference in New Issue
Block a user