Skip to main content

​
Overview

Tools enable you to discover, search, and execute actions across your Apigene applications. Agent mode adds context tools and Agent Skills-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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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). 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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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 (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: 
{
  "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..."
  }
}

​
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