[pull] main from activepieces:main

docs/about/changelog.mdx

@@ -4,6 +4,39 @@ description: "A log of all notable changes to Activepieces"
 icon: "code-commit"
 ---
 
+<Update label="August 2026" description="AI-Ready Pieces: Tool Search, AI Metadata & Audience">
+
+### AI-ready pieces: tool search, AI metadata, and audience
+
+The piece catalog is now built for AI agents as much as for humans. An agent connected
+through the [MCP server](/mcp/overview) can find the right action across hundreds of
+pieces by describing the task — then inspect its schema and run it.
+
+**Tool search**
+
+- **Search by task, not by name**: the new `ap_search_actions` and `ap_search_triggers`
+  MCP tools take a plain-language description (*"send a message to a Slack channel"*)
+  and return the most relevant actions or triggers, ranked by semantic similarity.
+  See [Tool Search](/mcp/tool-search).
+- **Honest no-match**: results below a relevance threshold are dropped rather than
+  padded, so agents don't grab a wrong tool when nothing fits.
+- **Self-host ready**: turn it on with `AP_TOOL_SEARCH_ENABLED`; semantic ranking uses
+  an OpenAI key, with a keyword fallback when none is configured.
+
+**AI metadata & audience**
+
+- **Agent-oriented descriptions**: actions and triggers across the catalog carry
+  `aiMetadata` — a description written for agents plus an idempotency declaration for
+  safe retries. See [AI Metadata](/build-pieces/piece-reference/ai-metadata).
+- **Audience targeting**: actions can target humans, agents, or both — the visual
+  builder shows the human view while agents discover the AI view, so agent-only
+  atomic actions don't clutter the piece selector.
+- **Output schemas**: pieces can declare a labelled, formatted presentation of their
+  step output, driving the builder's data selector and output viewer.
+  See [Output Schema](/build-pieces/piece-reference/output-schema).
+
+</Update>
+
 <Update label="June 2026" description="Production Setup: Lightweight Workers, Bundled Pieces & Predictable Scaling">
 
 ### Production setup: lightweight workers, bundled pieces, and predictable scaling

docs/build-pieces/piece-reference/ai-metadata.mdx

@@ -0,0 +1,74 @@
+---
+title: "AI Metadata"
+icon: "robot"
+description: "Make your piece's actions and triggers discoverable and safe for AI agents"
+---
+
+Every action and trigger you build is also an AI tool: agents connected through the [MCP server](/mcp/overview) discover piece actions and execute them directly. Two optional fields control how your piece appears to agents — `aiMetadata` describes the operation in agent terms, and `audience` controls which surfaces an action shows up in. Both are additive: omitting them leaves the piece behaving exactly as before.
+
+## aiMetadata
+
+Available on both actions and triggers:
+
+```typescript
+aiMetadata: {
+  description: string,   // optional — agent-oriented description
+  idempotent: boolean,   // optional — is repeating the call with the same input safe?
+}
+```
+
+**`description`** is written for an agent, not for the UI. The regular `description` stays a short label under the action name in the builder; `aiMetadata.description` can be a full paragraph that states what the operation does, its notable options and constraints, and how it differs from sibling actions ("Use *Send Message To A User* for a private DM"). This text feeds the [tool search](/mcp/tool-search) index, so a precise description directly improves whether agents find your action.
+
+**`idempotent`** declares whether calling the operation twice with the same input is safe. Reads, upserts, and set-value operations are idempotent; anything that creates, sends, or appends on every call is not. The value is exposed to agents and MCP clients as metadata that informs whether a retry is safe — it does not by itself prevent or trigger retries.
+
+```typescript
+import { createAction } from '@activepieces/pieces-framework';
+
+export const createTask = createAction({
+  name: 'create_task',
+  displayName: 'Create Task',
+  description: 'Create a task in a project',
+  aiMetadata: {
+    description:
+      'Create a new task in a given project, with optional assignee, due date, and labels. ' +
+      'Each call creates a new task, so it is not idempotent. ' +
+      'Use Update Task to modify an existing task instead.',
+    idempotent: false,
+  },
+  props: {
+    /* ... */
+  },
+  run: async (context) => {
+    /* ... */
+  },
+});
+```
+
+## audience
+
+Available on actions only (triggers have no audience — they always start flows, which both humans and agents build):
+
+```typescript
+audience: 'human' | 'ai' | 'both'
+```
+
+| Value | Visual builder | AI agents |
+|---|---|---|
+| `both` (default when omitted) | Shown | Shown |
+| `human` | Shown | Hidden from agent discovery |
+| `ai` | Hidden from the piece selector | Shown |
+
+Mark an action `human` when it only makes sense with the builder around it — for example the generic custom API call, or composite actions whose inputs assume a person picking from dropdowns. Mark an action `ai` for atomic operations added specifically for agents that would clutter the human piece selector.
+
+<Note>
+`audience` is a discovery filter, not a permission. It controls which catalogs an action appears in — it does not prevent execution, so don't rely on it to keep a dangerous action away from agents.
+</Note>
+
+## Writing actions agents can use well
+
+Agents work best with actions that behave like clean API calls:
+
+- **Atomic over composite.** One action should map to one capability with explicit inputs. Agents compose multi-step work themselves, so a focused *Create Task* beats a *Create Task and Notify Channel*.
+- **Explicit inputs.** Every behavior should be reachable through a documented prop — agents fill inputs from the [property schema](/build-pieces/piece-reference/properties), not from a UI.
+- **Describe the output.** Pair the action with an [output schema](/build-pieces/piece-reference/output-schema) so both the data selector and agents know the shape of what comes back.
+- **Disambiguate in `aiMetadata.description`.** When a piece has several similar actions, say which one to use when — that sentence is often what decides which action the search returns.

docs/docs.json

@@ -121,7 +121,8 @@
                   "group": "MCP Server",
                   "pages": [
                      "mcp/overview",
-                     "mcp/tools"
+                     "mcp/tools",
+                     "mcp/tool-search"
                   ]
                },
                {
@@ -376,6 +377,7 @@
                      "build-pieces/piece-reference/examples",
                      "build-pieces/piece-reference/custom-api-calls",
                      "build-pieces/piece-reference/output-schema",
+                     "build-pieces/piece-reference/ai-metadata",
                      "build-pieces/piece-reference/i18n"
                   ]
                },

docs/install/reference/environment-variables.mdx

@@ -46,6 +46,9 @@ Variables marked ❗ are required for a self-hosted production deployment.
   <Card title="Pieces & flows" icon="puzzle-piece" href="#pieces-&-flows">
     Piece syncing, polling, publish behavior.
   </Card>
+  <Card title="Tool search" icon="magnifying-glass" href="#tool-search">
+    Semantic action discovery for AI agents.
+  </Card>
 </CardGroup>
 
 ---
@@ -256,3 +259,15 @@ flow-authoring defaults.
 | `AP_ENABLE_FLOW_ON_PUBLISH` | Automatically enable a flow when a new version is published. | `true` |
 | `AP_ENFORCE_CONNECTION_PIECE_BINDING` | Reject a step's connection at runtime unless the connection was created for the same piece as the step. | `false` |
 | `AP_LOAD_TRANSLATIONS_FOR_DEV_PIECES` | Load translations for dev pieces (configured via `AP_DEV_PIECES`). Affects development mode only. | `false` |
+
+---
+
+### Tool search
+
+Semantic discovery of piece actions and triggers for AI agents connected
+through the MCP server. See [Tool Search](/mcp/tool-search) for how it works.
+
+| Variable | Description | Default |
+|---|---|---|
+| `AP_TOOL_SEARCH_ENABLED` | Registers the `ap_search_actions` and `ap_search_triggers` MCP tools. Read live, so flipping it takes effect without a restart. | `false` |
+| `AP_OPENAI_API_KEY` | OpenAI API key that funds tool-search embeddings (indexing and queries). When unset, the platform's OpenAI [AI provider](/admin-guide/guides/setup-ai-providers) is used instead; with neither, tool search serves keyword matches rather than semantic ones. | `None` |

docs/mcp/overview.mdx

@@ -51,15 +51,15 @@ Tools are organized into categories. **Discovery tools** are always available. O
 
 | Category | Description |
 |----------|-------------|
-| Discovery | Read-only tools for exploring flows, pieces, connections, tables, runs, and validation |
+| Discovery | Read-only tools for exploring flows, pieces, connections, tables, runs, and validation — including semantic search over the action and trigger catalog |
 | Flow Management | Create, duplicate, rename, publish, and enable/disable flows |
 | Flow Building | Add, update, and delete steps and triggers |
 | Router & Branching | Add, update, and delete conditional branches |
 | Annotations | Manage canvas notes |
 | Tables | Full CRUD for tables, fields, and records |
 | Testing & Runs | Test flows, inspect results, retry failures |
 
-See the [Tools Reference](/mcp/tools) for the complete catalog with input schemas.
+See the [Tools Reference](/mcp/tools) for the complete catalog with input schemas, and [Tool Search](/mcp/tool-search) for how agents find the right action or trigger by describing a task in plain language.
 
 ## Self-Hosting Behind a Reverse Proxy
 

docs/mcp/tool-search.mdx

@@ -0,0 +1,49 @@
+---
+title: "Tool Search"
+icon: "magnifying-glass"
+description: "Semantic discovery of piece actions and triggers for AI agents"
+---
+
+Tool search lets an AI agent find the right piece action or trigger by describing the task in plain language. Instead of paging through a catalog of hundreds of pieces, the agent calls [`ap_search_actions`](/mcp/tools#ap_search_actions) or [`ap_search_triggers`](/mcp/tools#ap_search_triggers) with a query like *"send a message to a Slack channel"* and gets back the few most relevant matches, ranked by semantic similarity.
+
+## The discovery workflow
+
+Search is the first step of the three-step workflow the MCP server is built around:
+
+1. **Discover** — `ap_search_actions` returns candidate actions: piece name, action name, a one-line description, whether the action needs a connection, and whether the project already has one for that piece.
+2. **Inspect** — `ap_get_piece_props` returns the full input schema for the chosen action.
+3. **Execute** — `ap_run_action` runs it once, or `ap_build_flow` wires it into a persistent automation.
+
+`ap_search_triggers` plays the same discovery role when the agent is building a flow and needs the event that should start it.
+
+## How results are ranked
+
+Every action and trigger in the piece catalog is indexed from its metadata, including [AI metadata](/build-pieces/piece-reference/ai-metadata) descriptions written specifically for agents. At query time the task description is embedded and compared against that index, and matches below a relevance threshold are dropped rather than padded — an empty result genuinely means nothing in the catalog fits, so the agent can say so instead of running a wrong tool. Actions marked human-only (`audience: 'human'`) are excluded from agent discovery.
+
+## Search modes
+
+| Mode | When | Behavior |
+|---|---|---|
+| `semantic` | An embedding model is configured | Meaning-based ranking with a relevance threshold |
+| `keyword` | No embedding model, or the embedding call failed | Lexical catalog search — the tools stay available, but matches are keyword-based |
+
+Every response includes the active `mode`, so a degraded instance is always detectable from the client side.
+
+## Availability
+
+Tool search is enabled on Activepieces Cloud. Self-hosted instances turn it on with an environment variable:
+
+```bash
+AP_TOOL_SEARCH_ENABLED=true
+```
+
+When the flag is off, `ap_search_actions` and `ap_search_triggers` are not registered on the MCP server. The flag is read live, so flipping it does not require a restart.
+
+Semantic mode needs two more things:
+
+- **An OpenAI API key** to fund the embeddings — either set `AP_OPENAI_API_KEY`, or configure OpenAI as an [AI provider](/admin-guide/guides/setup-ai-providers) in the platform admin. The environment variable takes precedence and is the simplest path for single-tenant deployments.
+- **The pgvector extension** available in your Postgres server. Activepieces creates the extension automatically at startup when the server supports it (for example the official `pgvector/pgvector` images and most managed Postgres offerings).
+
+If either is missing, tool search serves keyword mode instead of failing. The search index is built automatically on startup and kept in sync with the piece catalog — there is nothing to maintain by hand.
+
+See [Environment Variables](/install/reference/environment-variables#tool-search) for the full variable reference.

docs/mcp/tools.mdx

@@ -39,6 +39,15 @@ Read the full source code, package.json, and input mappings of a CODE step. Retu
 Use this tool when you need to read or edit a CODE step's full source. `ap_flow_structure` truncates code for overview purposes, so always call `ap_read_step_code` before modifying a code step.
 </Tip>
 
+### ap_read_step_settings
+
+Read the full untruncated settings of any step, including the trigger: piece input, action/trigger name, loop items, router branches, and error handling options. Use this to see a step's current configuration before updating it — `ap_flow_structure` truncates piece input.
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| `flowId` | string | Yes | The flow ID |
+| `stepName` | string | Yes | The step name (e.g., `trigger`, `step_1`). Use `ap_flow_structure` to get valid values. |
+
 ### ap_validate_flow
 
 Validate a flow for structural issues without publishing. Checks step validity, template references, and empty branches.
@@ -58,6 +67,34 @@ Research available pieces. Use `pieceNames` for bulk exact lookup (always return
 | `includeActions` | boolean | No | Include action details (only applies to searchQuery mode) |
 | `includeTriggers` | boolean | No | Include trigger details (only applies to searchQuery mode) |
 
+### ap_search_actions
+
+Find piece actions by describing the task in natural language (e.g. *"send a message to a Slack channel"*). Returns the most relevant actions ranked by semantic similarity, or an empty list when nothing in the catalog matches — the tool does not force a match. Each result includes the piece name, action name, a one-line description, whether the action needs a connection, and a `connected` flag indicating whether the project already has a connection for that piece.
+
+Available when [tool search](/mcp/tool-search) is enabled on the instance.
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | string | Yes | Natural-language description of the task to accomplish |
+| `limit` | number | No | Max matches to return (default 5, max 20) |
+| `pieceName` | string | No | Restrict results to a single piece (e.g. `slack`). Omit to search the whole catalog. |
+
+<Tip>
+This is the discovery step of the run-action workflow: take a result's `pieceName` + `actionName` to `ap_get_piece_props` for the input schema, then execute with `ap_run_action`.
+</Tip>
+
+### ap_search_triggers
+
+Find piece triggers (the event that starts a flow) by describing when the flow should run (e.g. *"when a new row is added to a Google Sheet"*). Same behavior and result shape as `ap_search_actions`, returning trigger names instead of action names.
+
+Available when [tool search](/mcp/tool-search) is enabled on the instance.
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| `query` | string | Yes | Natural-language description of the event that should start the flow |
+| `limit` | number | No | Max matches to return (default 5, max 20) |
+| `pieceName` | string | No | Restrict results to a single piece. Omit to search the whole catalog. |
+
 ### ap_get_piece_props
 
 Get the detailed input property schema for a specific piece action or trigger. Returns field names, types, required/optional, descriptions, default values, and dropdown options. When auth is required but not provided, automatically lists available connections. Use this before `ap_update_step` or `ap_update_trigger` to know exactly which fields to set.

packages/pieces/community/serp-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activepieces/piece-serp-api",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "scripts": {

packages/pieces/community/serp-api/src/lib/actions/search-apple-app-store.ts

@@ -12,7 +12,7 @@ export const searchAppleAppStore = createAction({
   audience: 'ai',
   aiMetadata: {
     description:
-      'Searches the Apple App Store via SerpApi for iOS apps matching a term, returning results in `organic_results` (app name, developer, rating, price, link). Use to discover iOS apps or look up an app by name. For Android apps use Search Google Play instead. Read-only and idempotent; requires the search term and a SerpApi API key.',
+      'Search the Apple App Store for iOS apps matching a name or keyword. Use to discover iOS apps, look up a specific app, or check an app\'s developer, rating, and price. For Android apps use Search Google Play instead.',
     idempotent: true,
   },
   outputSchema: searchAppleAppStoreOutputSchema,

packages/pieces/community/serp-api/src/lib/actions/search-bing.ts

@@ -12,7 +12,7 @@ export const searchBing = createAction({
   audience: 'ai',
   aiMetadata: {
     description:
-      'Runs a Bing web search via SerpApi and returns organic web results (in `organic_results`) for a query. Use as an alternative web engine to cross-check or supplement Google web results. Paginate with Count (results per page) and First (offset of the first result). Read-only and idempotent; requires the query and a SerpApi API key.',
+      'Search the web with Bing and get ranked organic results for a query. Use as an alternative web search engine to cross-check or supplement Google web results. Paginate with Count (results per page) and First (offset of the first result).',
     idempotent: true,
   },
   outputSchema: searchBingOutputSchema,

packages/pieces/community/serp-api/src/lib/actions/search-duckduckgo.ts

@@ -12,7 +12,7 @@ export const searchDuckduckgo = createAction({
   audience: 'ai',
   aiMetadata: {
     description:
-      'Runs a DuckDuckGo web search via SerpApi and returns organic web results (in `organic_results`) for a query. Use as a privacy-oriented alternative web engine to cross-check or supplement Google and Bing web results. Scope results to a region with the Region code. Read-only and idempotent; requires the query and a SerpApi API key.',
+      'Search the web with DuckDuckGo and get ranked organic results for a query. Use as a privacy-oriented alternative web search engine to cross-check or supplement Google and Bing web results. Scope results to a region with the Region code.',
     idempotent: true,
   },
   outputSchema: searchDuckduckgoOutputSchema,

packages/pieces/community/serp-api/src/lib/actions/search-google-images.ts

@@ -12,7 +12,7 @@ export const searchGoogleImages = createAction({
   audience: 'ai',
   aiMetadata: {
     description:
-      'Searches Google Images via SerpApi for a query, returning results in `images_results` (thumbnail URL, full-resolution image URL, title, and source page). Use to discover images, find a full-resolution URL, or locate the page an image came from. Page through results with the page index. Read-only and idempotent; requires the query and a SerpApi API key.',
+      'Search Google Images for pictures and photos matching a query. Use to discover images on a topic, find a full-resolution image URL, or locate the page an image came from. Page through results with the page index.',
     idempotent: true,
   },
   outputSchema: searchGoogleImagesOutputSchema,