> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apigene.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Gateway Tools

> Complete reference for all available tools

## Overview

Tools enable you to discover, search, and execute actions across your Apigene applications. Agent mode adds context tools and [Agent Skills](https://github.com/agentskills/agentskills)-compatible skill listing, retrieval, and creation. When MCP App UI is enabled, additional tools render results in UI widgets. All tools follow the standard MCP tool calling protocol.

## Tools Reference

### get\_instructions

Get the complete agent instructions and capabilities.

**Available in:** Agent mode only

**Parameters:** None

**Returns:** Agent instructions including description, guidelines, and available apps

**Example:**

```json theme={null}
{
  "tool": "get_instructions",
  "arguments": {}
}
```

### list\_available\_apps

List all available applications in the agent.

**Available in:** Agent mode only

**Parameters:**

* `include_action_summaries` (boolean, optional): Include action summaries (default: `true`)
* `max_action_summary` (number, optional): Max summaries per app (default: `20`)

**Returns:** List of applications with optional action summaries

**Example:**

```json theme={null}
{
  "tool": "list_available_apps",
  "arguments": {
    "include_action_summaries": true,
    "max_action_summary": 10
  }
}
```

### list\_actions

Retrieve actions from one or multiple applications.

**Available in:** Both MCP and Agent modes

**Parameters:**

* `requests` (array, required): Array of action requests, each containing:
  * `app_name` (string, required): Application identifier
  * `operationIds` (array, optional): Specific action IDs to fetch. If omitted, returns all actions
  * `detail_level` (string, optional): `"summary"` or `"full"` (default: `"full"`)

**Usage Modes:**

* **Discovery Mode**: Omit `operationIds` to get all actions (use `detail_level: "summary"` for lightweight listing)
* **Details Mode**: Provide `operationIds` to get full parameter schemas

**Returns:** Array of actions or object with app names as keys (for multiple apps)

**Example:**

```json theme={null}
{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "detail_level": "summary"
      }
    ]
  }
}
```

### search\_actions

Search across all agentic metadata to find relevant actions.

**Available in:** Both MCP and Agent modes

**Parameters:**

* `query` (string, optional): Free text search
* `action_type` (string, optional): Filter by type (get, search, add, update, delete, execute)
* `resource` (string, optional): Filter by resource type
* `min_rating` / `max_rating` (number, optional): Filter by rating
* `required_input` (string, optional): Only actions requiring this parameter
* `max_results` (number, optional): Maximum results to return
* `detail_level` (string, optional): `"summary"` or `"full"` (default: `"full"`)

**Returns:** Filtered list of matching actions. When nothing matches, the response may include `actions`, a short `message`, and `suggestions` (for example: broaden the query, use `list_available_apps`, or use `list_actions` for a specific app) instead of only an empty list.

**Example:**

```json theme={null}
{
  "tool": "search_actions",
  "arguments": {
    "query": "send message",
    "detail_level": "summary"
  }
}
```

### run\_action

Execute a single action for a specific application.

**Available in:** Both MCP and Agent modes

**Parameters:**

* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `context` (object, required): Action parameters including `operationId`
* `response_format` (string, optional): `"raw"` or `"formatted_md"` (default: `"raw"`)
* `response_projection` (string, optional): JMESPath expression to transform response
* `customer_execution_context` (object, optional): Customer-specific context
* `reasoning` (string, optional): Short explanation of why this action was chosen; supports decision tracing in agent workflows

**Returns:** Action execution result

**Example:**

```json theme={null}
{
  "tool": "run_action",
  "arguments": {
    "app_name": "Slack",
    "user_input": "Send a message to #general",
    "context": {
      "operationId": "chat.postMessage",
      "channel": "#general",
      "text": "Hello, world!"
    }
  }
}
```

### run\_action\_batch

Execute the same action multiple times in parallel with different parameters.

**Available in:** Both MCP and Agent modes

**Parameters:**

* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `base_context` (object, required): Shared parameters (must include `operationId`)
* `batch_context` (array, required): Array of varying parameters, one per execution
* `response_format` (string, optional): Output format
* `response_projection` (string, optional): JMESPath expression
* `customer_execution_context` (object, optional): Customer context

**Returns:** Object with `batch_results` array and `summary` statistics

**Example:**

```json theme={null}
{
  "tool": "run_action_batch",
  "arguments": {
    "app_name": "Gmail",
    "user_input": "Read multiple emails",
    "base_context": {
      "operationId": "readEmail"
    },
    "batch_context": [
      { "email_id": "123" },
      { "email_id": "456" },
      { "email_id": "789" }
    ]
  }
}
```

### run\_multi\_actions

Execute multiple different actions in parallel across different applications.

**Available in:** Both MCP and Agent modes

**Parameters:**

* `actions` (array, required): Array of action requests, each containing:
  * `app_name` (string, required)
  * `user_input` (string, required)
  * `context` (object, required): Must include `operationId`
  * `response_format` (string, optional)
  * `response_projection` (string, optional)
  * `customer_execution_context` (object, optional)
  * `template_id` (string, optional): Only set when a specific MCP App template should render that action’s result in the UI

**Returns:** Object with `results` array and `summary` statistics

**Example:**

```json theme={null}
{
  "tool": "run_multi_actions",
  "arguments": {
    "actions": [
      {
        "app_name": "Gmail",
        "user_input": "Get latest email",
        "context": { "operationId": "getLatestEmail" }
      },
      {
        "app_name": "Jira",
        "user_input": "List my tasks",
        "context": { "operationId": "listIssues", "assignee": "me" }
      }
    ]
  }
}
```

### run\_action\_ui

Execute a single action with MCP App UI rendering so results can be shown in a visual widget (when your host supports MCP Apps).

**Available in:** Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment.

**Parameters:**

* `app_name` (string, required): Application identifier
* `user_input` (string, required): Natural language description
* `context` (object, required): Action parameters including `operationId`
* `response_format` (string, optional): `"raw"` or `"formatted_md"` (default: `"raw"`)
* `customer_execution_context` (object, optional): Customer-specific context
* `reasoning` (string, optional): Why this action was chosen
* `template_id` (string, optional): Only include when the user explicitly requests a specific template; otherwise omit so the default template applies

**Returns:** Action result; when a template applies, the response includes data suitable for the UI resource (see [MCP Gateway Resources](/user-guide/mcp-gateway/mcp-gateway-resources)).

**Note:** Unlike `run_action`, this tool does not accept `response_projection`.

### run\_multi\_actions\_ui

Execute multiple different actions in parallel with MCP App UI rendering (for example a grid or mesh layout comparing outputs).

**Available in:** Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment.

**Parameters:**

* `actions` (array, required): Same shape as `run_multi_actions` (each item may include `template_id` when a specific template is requested)

**Returns:** Combined results with UI-oriented payload for supported hosts.

### list\_contexts

List all available contexts and context type definitions.

**Available in:** Agent mode only

**Parameters:** None

**Returns:** Object with `contexts` array and `context_types` array

**Example:**

```json theme={null}
{
  "tool": "list_contexts",
  "arguments": {}
}
```

### get\_context

Get detailed information about a specific context.

**Available in:** Agent mode only

**Parameters:**

* `context_id` (string, required): The context identifier

**Returns:** Full context details

**Example:**

```json theme={null}
{
  "tool": "get_context",
  "arguments": {
    "context_id": "ctx_123"
  }
}
```

### search\_contexts

Search for contexts with flexible filtering.

**Available in:** Agent mode only

**Parameters:**

* `query` (string, optional): Search query
* `type` (string, optional): Filter by context type
* `status` (string, optional): Filter by status (default: `"active"`)
* `max_results` (number, optional): Maximum results (default: `5`)

**Returns:** Object with matching `contexts` and `context_types`

**Example:**

```json theme={null}
{
  "tool": "search_contexts",
  "arguments": {
    "query": "customer support",
    "type": "Knowledge"
  }
}
```

### add\_context

Create a new context in the system.

**Available in:** Agent mode only

**Parameters:**

* `name` (string, required): Unique context name
* `description` (string, required): Detailed description
* `summary` (string, optional): Short summary
* `when_to_use` (string, optional): Usage guidelines
* `type` (string, optional): Context type (must match existing types)
* `apps` (array, optional): Associated app names
* `status` (string, optional): `"active"` or `"disabled"` (default: `"active"`)

**Returns:** Created context object

**Example:**

```json theme={null}
{
  "tool": "add_context",
  "arguments": {
    "name": "Customer Support Guidelines",
    "description": "Guidelines for handling customer support requests...",
    "summary": "Support handling guidelines",
    "type": "Knowledge",
    "apps": ["Zendesk", "Slack"]
  }
}
```

### list\_skills

List skill metadata attached to the agent (Agent Skills style). Does not return the full `SKILL.md` body; use `get_skill_content` for that.

**Available in:** Agent mode only

**Parameters:**

* `detail_level` (string, optional): `"summary"` (id, name, description only; fewer tokens) or `"full"` (all metadata fields; default: `"full"`)

**Returns:** Object with `skill_list` entries. Summary mode is best for discovery; full mode includes fields such as license, compatibility, metadata, allowed tools, status, and timestamps.

**Example:**

```json theme={null}
{
  "tool": "list_skills",
  "arguments": {
    "detail_level": "summary"
  }
}
```

### get\_skill

Fetch one skill by id: metadata plus optional packaged files (`scripts`, `references`, `assets`). Does not return the main `SKILL.md` body; use `get_skill_content` for the instruction text.

**Available in:** Agent mode only

**Parameters:**

* `skill_id` (string, required): Skill identifier

**Returns:** Object with a `skill` payload (metadata and optional path→content maps for scripts, references, assets).

**Example:**

```json theme={null}
{
  "tool": "get_skill",
  "arguments": {
    "skill_id": "sk_abc123"
  }
}
```

### get\_skill\_content

Return the full `SKILL.md` content for a skill (YAML front matter plus Markdown body).

**Available in:** Agent mode only

**Parameters:**

* `skill_id` (string, required): Skill identifier

**Returns:** Object with a `content` string.

**Example:**

```json theme={null}
{
  "tool": "get_skill_content",
  "arguments": {
    "skill_id": "sk_abc123"
  }
}
```

### add\_skill

Create a new skill and attach it to the current agent. Content should follow the [Agent Skills specification](https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx) (valid name format, description length, structured front matter, reasonably sized body with long reference material in `references/` when needed).

**Available in:** Agent mode only

**Parameters:**

* `name` (string, required): Skill name (lowercase, hyphens; per spec)
* `description` (string, required): What the skill does and when to use it
* `content` (string, required): Full `SKILL.md` (front matter + Markdown body)
* `license` (string, optional)
* `compatibility` (string, optional)
* `metadata` (object, optional)
* `allowed_tools` (string, optional)
* `status` (string, optional): `"active"` or `"disabled"` (default: `"active"`)
* `scripts` (object, optional): Map of file path to content under `scripts/`
* `references` (object, optional): Map of file path to content under `references/`
* `assets` (object, optional): Map of file path to content under `assets/`

**Returns:** The created skill record.

**Example:**

```json theme={null}
{
  "tool": "add_skill",
  "arguments": {
    "name": "my-workflow",
    "description": "Steps for our internal review workflow.",
    "content": "---\nname: my-workflow\ndescription: Steps for our internal review workflow.\n---\n\n## When to use\n..."
  }
}
```

## Recommended Workflows

### Discovering and Executing Actions

1. **Discovery**: Use `list_actions` with `detail_level: "summary"` to find relevant actions
2. **Get Details**: Use `list_actions` with `operationIds` to get full parameter schemas
3. **Execute**: Use `run_action` with complete parameters

### Searching for Actions

1. **Search**: Use `search_actions` with `detail_level: "summary"` to find actions
2. **Get Details**: Use `list_actions` with specific `operationIds` for full schemas
3. **Execute**: Use `run_action` with proper parameters

### Batch Operations

1. **Identify Action**: Find the action you want to execute multiple times
2. **Prepare Batch**: Create `base_context` with shared parameters and `batch_context` with varying parameters
3. **Execute**: Use `run_action_batch` for parallel execution

### Skills

1. **Discover**: `list_skills` with `detail_level: "summary"` to see what exists
2. **Read instructions**: `get_skill_content` for the main `SKILL.md` body when activating a skill
3. **Optional files**: `get_skill` if you need scripts, references, or assets
4. **Create**: `add_skill` when adding a new skill to the agent (follow Agent Skills formatting rules)

## Response Formatting

### response\_format Parameter

* `"raw"` (default): Returns exact API response
* `"formatted_md"`: Returns Markdown-formatted response (use when explicitly requested)

### response\_projection Parameter

Use JMESPath expressions to transform and reduce response size:

* **Field Selection**: `"{name: name, email: email}"`
* **Array Extraction**: `"items[*].name"`
* **Filtering**: `"items[?price > 100]"`
* **Aggregation**: `"sum(items[*].price)"`

## Error Handling

Tools return standard error responses when:

* Authentication fails
* Required parameters are missing
* Action execution fails
* Invalid operation IDs are provided

Check the error message for specific details about what went wrong.

## Next Steps

* [Learn about resources](/user-guide/mcp-gateway/mcp-gateway-resources)
* [See usage examples](/user-guide/mcp-gateway/mcp-gateway-examples)