Skip to content
Skills Library
AI & agents · Building & coding

tools-setup

/tools-setup

Use when creating, updating or configuring Cognigy agent tools (create_tool, update_tool) — choosing the tool type (tool, http, mcp, knowledge, send_email, a2a) and their configuration schemas.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when creating, updating or configuring Cognigy agent tools (create_tool, update_tool) — choosing the tool type (tool, http, mcp, knowledge, send_email, a2a) and their configuration schemas.

Original author description

Use when creating, updating or configuring Cognigy agent tools (create_tool, update_tool) — choosing the tool type (tool, http, mcp, knowledge, send_email, a2a) and their configuration schemas.

How it works

  1. What are tools?
  2. Steps
  3. Parameter schema rules (config.parameters)
  4. Tool types (createtool)
  5. Accessing tool parameters in code
  6. Adding logic inside tools (manageflownodes)
  7. Updating tools (updatetool)
  8. Managing tools
  9. Tools under an LLM Prompt node (flowId addressing)
  10. Prerequisites
Original SKILL.md headings · 356 lines, 2,330 words
SKILL.md preview
---
name: tools-setup
description: "Use when creating, updating or configuring Cognigy agent tools (create_tool, update_tool) — choosing the tool type (tool, http, mcp, knowledge, send_email, a2a) and their configuration schemas."
---

# Adding Tools to an AI Agent

## What are tools?

Tools give an AI Agent capabilities beyond conversation — calling APIs, executing code, or searching knowledge bases. Without tools, an agent can only chat.

## Steps

1. Create the agent first: create_ai_agent { projectId, name, description }
   (create_tool requires an agent with an auto-provisioned flow)
2. create_tool { aiAgentId, toolType, name, config }
3. The tool is automatically wired into the agent's flow
4. Test with talk_to_agent

Rule of thumb: each tool in an agent flow should have a unique `toolId`. If you need more logic, parameters, validation, or HTTP calls for that tool, add them inside the same tool branch instead of creating another tool with the same `toolId`.

## Parameter schema rules (config.parameters)

`parameters` is a JSON Schema string that Cognigy passes VERBATIM to the LLM provider. create_tool / update_tool validate it and reject violations, because a broken schema either fails every conversation turn with a provider 400 (strict models) or is silently dropped (the tool is called with no arguments). The contract:

- Top level: `{"type":"object","properties":{...},"required":[...]}` — `required` is mandatory (use `[]` if nothing is required).
- EVERY property needs `"type"` AND `"description"`. Allowed types: `string`, `number`, `integer`, `boolean`, `object`, `array`, `null`.
- `array` properties need `"items"`. Nested objects with `"properties"` also need their own `"required"`.
- `"additionalProperties": false` is injected automatically at every object level.
- Strict-mode models (OpenAI Responses API, e.g. gpt-5.x, where strict is forced on): list EVERY property key in `required`; make a parameter optional with a nullable type — `{"type":["string","null"],"description":"..."}`. Non-strict providers ignore this, so it is the safe default.
- Nested object properties and `integer` are valid at runtime but not renderable by the Cognigy UI's graphical parameter builder — the node's Parameters section then shows the raw JSON editor. That is cosmetic; prefer flat schemas when you don't need nesting.

## Tool types (create_tool)

Choosing the type:

- `tool` — the default for any business action ("unlock account", "check balance", "validate user"). Custom logic goes inside its branch via manage_flow_nodes.
- `http` — only when the user names a concrete HTTP/REST endpoint to call.
- `knowledge` — search a Knowledge Store (the store must exist first).
- `send_email` — send emails.
- `mcp` — only when the user explicitly asks to connect an external MCP server and gives its URL. Never a default.
- `a2a` — only for a remote A2A agent outside the project, or when the user explicitly asks for A2A. Agents in the same project use the native Handover to AI Agent tool instead (see the a2a-setup skill).

### tool — General-purpose tool with custom logic

```text
create_tool {
aiAgentId: "...",
toolType: "tool",
name: "Fetch Weather",
config: {
toolId: "fetch_weather",
description: "Fetches current weather for a city",
parameters: '{"type":"object","properties":{"city":{"type":"string","description":"City to fetch the weather for"}},"required":["city"]}',
toolResponseValue: "{{JSON.stringify(input.result)}}"
}
}
```

IMPORTANT: The node label in the flow uses `toolId` (snake_case), not the display `name`. Always provide `toolId`.

The Resolve Tool Action node is auto-created with an `answer` field that controls what is returned to the LLM. Default for general-purpose tools: `{{JSON.stringify(input.result)}}`. Set `toolResponseValue` to customize it.

### knowledge — Search a Knowledge Store

```text
create_tool {
aiAgentId: "...",
toolType: "knowledge",
name: "Search FAQ",
config: {
knowledgeStoreId: "507f1f77bcf86cd799439011",
toolId: "search_faq",
description: "Search the FAQ knowledge base"
}
}
```

### send_email — Send emails

```text
create_tool {
aiAgentId: "...",
toolType: "send_email",
name: "Send Email",
config: {
toolId: "send_email",
description: "Send an email to support",
recipient: "support@example.com"
}
}
```

### mcp — Connect to an EXTERNAL MCP server (specialized — not for general use)

⚠️ ONLY use this when the user explicitly asks to integrate with an external MCP (Model Context Protocol) server and provides a server URL. For general tool requests (e.g., "unlock account", "check status"), use toolType "tool" instead.

```text
create_tool {
aiAgentId: "...",
toolType: "mcp",
name: "External MCP",
config: {
mcpName: "my-mcp-server",
mcpServerUrl: "https://mcp.example.com",
timeout: 30
}
}
```

### a2a — Delegate to a remote A2A (Agent2Agent) agent (specialized — not for general use)

⚠️ ONLY use this when the target agent is outside the project (external or third-party, another project or tenant), or when the user explicitly asks for A2A. Do NOT use it just because a project has two agents that should be connected; agents in the same project use the native Handover to AI Agent tool (see the a2a-setup skill, "When NOT to use A2A"). The remote agent does NOT have to be a Cognigy agent — it can be any external/third-party A2A-compliant agent; `agentBaseUrl` is then just whatever base URL that agent publishes. See the a2a-setup skill for the full workflow.

GOTCHA (Cognigy-target only): if the remote agent IS a Cognigy agent deployed behind `manage_a2a_server`, `agentBaseUrl` must be that call's response `agentBaseUrl` field, used verbatim — a2aServer endpoints live under `/a2a/v1/<URLToken>`, not the plain endpoint URL. Using the wrong shape silently 404s. This gotcha does not apply to external agents.

```text
create_tool {
aiAgentId: "...",
toolType: "a2a",
name: "Flights Agent",
config: {
agentBaseUrl: "<external agent's own base URL, or agentBaseUrl from manage_a2a_server response>",
agentCardPath: ".well-known/agent.json",
executionMode: "blocking",
taskTimeout: 60
}
}
```

### http — Call an external HTTP API

Creates a composite node structure with optional pre/post-processing Code nodes:

aiAgentJobTool (the tool node the LLM sees)
└─ [Code node: pre-process] (optional)
└─ HTTP Request node (makes the API call)
└─ [Code node: post-process] (optional)

#### HTTP response shape — read this before writing postProcessCode

The HTTP Request node writes the response into the `input` object. Two things about this are not obvious from the schema and silently break tools when missed:

1. **Default storage key.** The response is stored at `input.httprequest` by default. This is the same key used in the default `toolResponseValue` of `{{JSON.stringify(input.httprequest)}}`.
2. **Wrapping.** The value at `input.httprequest` is NOT the raw response body. It is a wrapper object — typically:

   ```text
   input.httprequest = {
     result:     <parsed body>,   // JSON for application/json responses, string otherwise
     statusCode: 200,
     length:     <bytes>
   }
   ```

   So if the API returns `{ "meals": [...] }`, your `postProcessCode` reads `input.httprequest.result.meals`, NOT `input.httprequest.meals` and NOT `input.httprequest.body.meals`.

If you are unsure of the exact shape in your Cognigy version, instrument the post-process on the very first run (`input.debug = { keys: Object.keys(input.httprequest), sample: input.httprequest };`) instead of guessing — a wrong key returns `undefined`, the Resolve Tool Action serializes that, and the LLM honestly reports "no results found" even when the API call succeeded.

#### Code node rules

Both `preProcessCode` and `postProcessCode` run inside Cognigy Code nodes. Two rules apply:

- **No top-level `return`.** Code nodes are not full functions; the engine rejects `return` at the top level. Mutate `input` directly — `input.foo = bar;` instead of `return { foo: bar };`. If you need to short-circuit, set a flag and check it in a downstream node.
- **`input` is the only persistent surface.** Anything you write to `input.*` is visible to subsequent nodes (post-process, Resolve, downstream flow). Local `const`/`let` variables disappear at the end of the node.

#### Example — simple GET with post-processing

```text
create_tool {
aiAgentId: "...",
toolType: "http",
name: "Get Weather",
config: {
toolId: "get_weather",
description: "Fetches current weather for a location",
parameters: '{"type":"object","properties":{"city":{"type":"string","description":"City to fetch the weather for"}},"required":["city"]}',
url: "https://api.weather.com/v1/current?q={{input.aiAgent.toolArgs.city}}",
method: "GET",
headers: { "X-Api-Key": "your-api-key" },
postProcessCode: "input.weather = input.httprequest.result.current; delete input.httprequest;"
}
}
```

#### Example — POST with pre/post-processing and custom tool response

```text
create_tool {
aiAgentId: "...",
toolType: "http",
name: "Create Order",
config: {
toolId: "create_order",
description: "Creates a new order in the order management system",
parameters: '{"type":"object","properties":{"items":{"type":"array","description":"Ordered items","items":{"type":"string","description":"SKU of one item"}},"customerId":{"type":"string","description":"Customer identifier"}},"required":["items","customerId"]}',
url: "https://api.example.com/orders",
method: "POST",
headers: { "Authorization": "Bearer {{context.apiToken}}" },
body: "{{JSON.stringify(input.orderPayload)}}",
preProcessCode: "input.orderPayload = { items: input.aiAgent.toolArgs.items, customer: input.aiAgent.toolArgs.customerId, timestamp: new Date().toISOString() };",
postProcessCode: "input.orderResult = { orderId: input.httprequest.result.id, status: input.httprequest.result.status }; delete input.httprequest;",
toolResponseValue: "{{JSON.stringify(input.orderResult)}}"
}
}
```

#### Tool response value (toolResponseValue)

The `toolResponseValue` field controls what the Resolve Tool Action node returns to the LLM as the tool's result. This is a CognigyScript expression. It applies to BOTH `http` and general-purpose `tool` types.

Defaults (if omitted):

- **http tools**: `{{JSON.stringify(input.httprequest)}}` — returns the full wrapper described in _HTTP response shape_ above, not just the parsed body. For most tools you will want to override this with a trimmed payload from your `postProcessCode`.
- **general-purpose tools**: `{{JSON.stringify(input.result)}}` — returns the `input.result` field

IMPORTANT: The Resolve Tool Action node MUST have an `answer` value, otherwise nothing is returned to the LLM and the tool appears to produce no output. If your code stores results in a custom field, set toolResponseValue to match.

Common patterns:

- `{{JSON.stringify(input.result)}}` — return a processed result object (default for general-purpose tools)
- `{{JSON.stringify(input.orderResult)}}` — return a named result from post-processing
- `{{input.summary}}` — return a plain string value
- `{{JSON.stringify(input.httprequest.result)}}` — return only the parsed body of an HTTP response, dropping the `statusCode` / `length` wrapper

## Accessing tool parameters in code

Inside AI Agent tool branches, the LLM's tool call arguments are at `input.aiAgent.toolArgs`, **NOT** `input.data`. For example, if the tool defines a `city` parameter, access it as:

- Code nodes: `input.aiAgent.toolArgs.city`
- CognigyScript fields (URLs, body templates): `{{input.aiAgent.toolArgs.city}}`

**Under an LLM Prompt (`llmPromptV2`) node the path is different:** args land at `input.llmPrompt.toolArgs`, and `input.aiAgent` is `null`. Reading `input.aiAgent.toolArgs` there yields `undefined` — the tool then runs with no arguments and silently falls back (mock/default) with no error. For tools that may run under either node type, read defensively:

```js
const args =
  (input.llmPrompt && input.llmPrompt.toolArgs) ||
  (input.aiAgent && input.aiAgent.toolArgs) ||
  {};
```

## Adding logic inside tools (manage_flow_nodes)

After creating a `toolType: "tool"`, you can add flow nodes inside the tool's branch to build custom logic. This is the recommended way to add conversation logic — nodes should live inside tools, not as standalone nodes in the flow.

### Workflow

1. Create the tool — `create_tool` returns a `toolNodeId`
2. Add the first node using `parentNodeId` = toolNodeId and `mode` = `appendChild`
3. Add subsequent nodes using `parentNodeId` = previous node ID and `mode` = `append`

If you already created the tool for this action, stop there and reuse that same `toolNodeId`. Do not call `create_tool` again for the same `toolId`.

Note: Both `appendChild` and `append` work correctly when targeting a tool node. The handler automatically places new nodes in the correct execution chain (before the Resolve Tool Action node) regardless of which mode you use.

### Example — tool with validation logic and response

```
Step 1: Create the tool
create_tool {
  aiAgentId: "...",
  toolType: "tool",
  name: "Check Order Status",
  config: {
    toolId: "check_order_status",
    description: "Looks up the status of a customer order",
    parameters: '{"type":"object","properties":{"orderId":{"type":"string","description":"Order number to look up"}},"required":["orderId"]}'
  }
}
→ returns toolNodeId: "abc123..."

Step 2: Add a Code node inside the tool branch
manage_flow_nodes {
  operation: "create",
  flowId: "<flowId>",
  parentNodeId: "abc123...",
  mode: "appendChild",
  nodeType: "code",
  label: "Validate Order ID",
  config: { code: "if (!input.aiAgent.toolArgs.orderId) { input.error = 'Missing order ID'; }" }
}
→ returns nodeId: "def456..."

Step 3: Add an If/Else node after the Code node
manage_flow_nodes {
  operation: "create",
  flowId: "<flowId>",
  parentNodeId: "def456...",
  mode: "append",
  nodeType: "ifThenElse",
  label: "Has Error?",
  config: { condition: "{{input.error}}" }
}
```

### Supported node types for tool branches

All node types supported by `manage_flow_nodes` can be used inside tool branches: `say`, `question`, `ifThenElse`, `lookup`, `setSessionContext`, `code`, `goTo`, `sleep`, `httpRequest`.

See the flow-nodes skill for config schemas of each node type.

## Updating tools (update_tool)

Modify an existing tool node's label or config:

```text
update_tool {
aiAgentId: "...",
toolNodeId: "...",
name: "Updated Weather Tool",
config: { description: "Updated description for the LLM" }
}
```

For http tools, include HTTP fields in config to update child nodes:

```text
update_tool {
aiAgentId: "...",
toolNodeId: "...",
toolType: "http",
config: {
url: "https://api.weather.com/v2/current",
postProcessCode: "input.result = input.httprequest.result;"
}
}
```

If the tool was originally created without `preProcessCode` / `postProcessCode`, passing them here will provision and wire the missing Code node automatically — no need to delete and recreate the tool. To target a specific existing child by ID (useful after a rename, or when the tool's flow contains other tools with the same label prefix), pass `httpNodeId` / `preProcessNodeId` / `postProcessNodeId` / `resolveNodeId` from the `childNodes` block in `create_tool`'s response.

## Managing tools

- List: list_resources { resourceType: "tool", aiAgentId }
- Remove: delete_resource { resourceType: "tool", id: toolId, aiAgentId }
- Update: update_tool { aiAgentId, toolNodeId, name?, config? }
- Tool IDs come from create_tool response or list_resources
- Tool IDs must be unique within an agent flow. If a tool already exists for an action, reuse it.

## Tools under an LLM Prompt node (flowId addressing)

LLM Prompt (`llmPromptV2`) flows have no agent resource, so address their tools by `flowId`:

- Create: create_tool { flowId, toolType, name, config }
- List: list_resources { resourceType: "tool", flowId }
- Update: update_tool { flowId, toolNodeId, ... }
- Remove: delete_resource { resourceType: "tool", id: toolId, flowId }

Tools attach to the flow's aiAgentJob node when one exists, otherwise to its llmPromptV2 node. Under an LLM Prompt node, only `tool`, `mcp`, and `http` are supported. Branch logic works the same, **but the tool arguments arrive at `input.llmPrompt.toolArgs`, not `input.aiAgent.toolArgs`** (`input.aiAgent` is `null` in an LLM Prompt branch). Code and CognigyScript inside these tool branches must read `input.llmPrompt.toolArgs.<param>`; the `input.aiAgent.toolArgs` examples above apply only to AI Agent Job flows. See the flow-nodes guide's Notes for the defensive read that covers both.

Create LLM Prompt nodes only on explicit user request; see the flow-nodes guide.

## Prerequisites

- Agent MUST be created via create_ai_agent (not manually) — tools need the auto-provisioned flow
- For knowledge tools, the knowledge store must exist (use manage_knowledge first)

## Knowledge: tool vs persona-level

- **Default (ALWAYS use unless told otherwise)**: Use create_tool with toolType "knowledge" to attach knowledge stores. This gives the agent a dedicated search tool it can invoke during conversations.
- **Exception**: Only attach knowledge to the agent persona (via create_ai_agent or update_ai_agent) if the user EXPLICITLY asks to put it on the persona. Do not default to persona-level attachment.

Versions

The database has no other skills named tools-setup.

Database snapshot: 13.11.2026 · package version 61637fa54522 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100a2a-setup
    Use when the user explicitly asks for A2A (Agent2Agent), wants an agent to call an external / third-party A2A agent or one in another project or tenant, or wants to expose a Cognigy agent to outside A2A callers. Covers the manage_a2a_server endpoint and the create_tool {…
  • 100settings
    Use when configuring project-level Cognigy settings — voice preview / speech provider configuration and Knowledge AI settings.
  • 81mcp-setup
    Use when installing, configuring, debugging, or verifying an MCP server for a harness, or when a configured server's tools are missing or failing.
  • 90Agent Tools Reference
    Reference for available agent tools, built-in agent type tool presets, and the memory system. Use when configuring agent capabilities, choosing which tools agents need, understanding the memory system, selecting an agent base type, or checking what tools are available for agents.
  • 100tool-design
    This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces.
  • 100tool-creator
    This skill should be used when users want to create a new tool for the Strands SDK agent system. It supports creating both agent-as-a-tool (complex agents wrapped as tools) and regular tools (simple function-based tools). Use this skill when users request to create, build, or add a new tool.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.