# Add Tool

> Add a new MCP tool (or extend an existing one) in the NiCE Cognigy Plugin's MCP server

- Skill: `cognigy/add-tool` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cognigy/add-tool`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cognigy/add-tool/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Cognigy (https://skillmd.com/u/cognigy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cognigy/add-tool

---


Add a new MCP tool (or extend an existing one) in the NiCE Cognigy Plugin's MCP server. The user will describe the tool's purpose, operations, and Cognigy API endpoints it should call.

**Skills come first.** The plugin's user-facing surface is its skills — each describes a workflow and auto-loads on intent. Tools are the execution primitives a skill orchestrates. Work skill-first: figure out which workflow the capability belongs to, then add or extend a tool only where that workflow needs it. There is no one-skill-per-tool rule — many tools can serve a single workflow, and a new tool usually just slots into an existing skill.

## Context

This is a TypeScript MCP server. Tools follow a strict pattern across these files:

| File | Role |
|------|------|
| `src/tools/definitions.ts` | Tool metadata: name, description, annotations, inputSchema (JSON Schema) |
| `src/schemas/tools.ts` | Zod validation schemas — one per tool or discriminated union per multi-op tool |
| `src/tools/handlers.ts` | `ToolHandlers` class — one `handleXxx(args)` method per tool + a case in `handleToolCall()` |
| `plugin/skills/<name>/SKILL.md` | Hand-authored plugin skill for the tool (auto-loads on intent in supporting clients, e.g. Claude Code) |
| `src/__tests__/schemas.test.ts` | Schema validation tests |
| `src/__tests__/tools.test.ts` | Handler tests with mocked `CognigyApiClient` |

## Design philosophy: few tools, many operations

This server deliberately uses few tools (~16) to cover many Cognigy API endpoints (~115). Each tool groups related endpoints under a single `operation` parameter that acts as a router.

**Example: `manage_knowledge`** — one tool covers ~8 endpoints:
- `create_store` → `POST /v2.0/knowledgestores`
- `create_source` → `POST /v2.0/knowledgestores/{id}/sources`
- `list_sources` → `GET /v2.0/knowledgestores/{id}/sources`
- `ingest_source` → `POST /v2.0/knowledgestores/{id}/sources/{id}/ingest`
- `list_chunks` → `GET /v2.0/knowledgestores/{id}/chunks`
- etc.

**Why this pattern:**
- **Fewer tools for the LLM to choose from** — 16 tools is much easier for Claude to reason about than 115 separate ones. Less confusion, better tool selection.
- **Grouped by domain** — each tool maps to a Cognigy domain concept (knowledge, packages, webchat, flow nodes), making it intuitive.
- **Shared context** — operations within a tool share parameters (like `projectId`) and the description explains the full workflow across operations in one place.

**When to create a new tool vs. add an operation to an existing tool:**
- If the new functionality belongs to an existing domain (e.g. a new knowledge operation), add it as an operation to the existing tool.
- If it represents a new domain concept, create a new tool.
- Aim for each tool to average ~5-10 operations.

## Templates

Reference templates are bundled with this skill. Use them as starting points:

- **`${CLAUDE_SKILL_DIR}/templates/definition.ts`** — Tool definition entry for `src/tools/definitions.ts`
- **`${CLAUDE_SKILL_DIR}/templates/schema.ts`** — Zod schema for `src/schemas/tools.ts`
- **`${CLAUDE_SKILL_DIR}/templates/handler.ts`** — Handler method for `src/tools/handlers.ts`

Read these templates before writing code to match the exact conventions.

## Steps

### 1. Gather requirements

Before writing code, confirm with the user:
- Tool name (snake_case, e.g. `manage_packages`)
- Operations (if multi-operation tool) and their required/optional params
- Which Cognigy REST API endpoints each operation calls (method + path)
- Whether a plugin skill is needed for the tool's workflow
- Read existing tools in `src/tools/definitions.ts` and `src/schemas/tools.ts` to match conventions

### 2. Add the tool definition (`src/tools/definitions.ts`)

Read `${CLAUDE_SKILL_DIR}/templates/definition.ts` for the template.

Add an entry to the `tools` array. Conventions:
- Use 24-char hex IDs for all Cognigy resource IDs
- Keep descriptions actionable — tell the AI what the tool does and when to use it

### 3. Add Zod schema (`src/schemas/tools.ts`)

Read `${CLAUDE_SKILL_DIR}/templates/schema.ts` for the template.

- Single-operation tools use a plain `z.object()`
- Multi-operation tools use `z.discriminatedUnion("operation", [...])`
- The shared `idSchema` is already defined: `z.string().regex(/^[a-f0-9]{24}$/)`

### 4. Implement the handler (`src/tools/handlers.ts`)

Read `${CLAUDE_SKILL_DIR}/templates/handler.ts` for the template.

Add a method to the `ToolHandlers` class, then add the dispatch case in `handleToolCall()`.

Key patterns:
- Always parse args with the Zod schema first
- Use `this.apiClient.get/post/patch/delete/put/uploadFile` for API calls
- Use `filterResponse(resourceType, result)` to return summary views
- Use `withHints(data, { action: "helpful suggestion" })` for actionable errors
- Complex logic (preview generation, conflict resolution) goes in a separate file under `src/tools/` (e.g. `packageImport.ts`)

### 5. Wire the tool into a skill

Skills — not tools — are how users reach this capability, so connect the new tool to a workflow:

- **Existing workflow (most common)** — extend the relevant `plugin/skills/<id>/SKILL.md` so its steps use the new tool. Do NOT create a new skill just because you added a tool.
- **New workflow / intent** — only then create `plugin/skills/<id>/SKILL.md` with `name`/`description` frontmatter (the `description` is the auto-load trigger) followed by the workflow body. There is no registry step; it auto-loads on intent in supporting clients (e.g. Claude Code).

### 6. Add tests

**Schema tests** in `src/__tests__/schemas.test.ts`:
- Valid input passes parsing
- Missing required fields throw
- Invalid IDs throw
- Each operation variant is tested

**Handler tests** in `src/__tests__/tools.test.ts`:
- Mock `CognigyApiClient` methods (`jest.fn()`)
- Test each operation calls correct API endpoints
- Test error cases and edge cases
- Follow existing test structure with `describe`/`it` blocks

### 7. Verify

Run in order:
1. `npx tsc -p tsconfig.json --noEmit` — type check
2. `npm test -- --runInBand` — all tests pass
3. `npx prettier --write <changed-files>` — format only the files you created or modified

## Guidelines

- Match the style and conventions of existing tools exactly
- Do NOT add unnecessary complexity — keep operations focused
- Every Cognigy ID parameter should validate with `idSchema` (24-char hex)
- Multi-operation tools should use discriminated unions (both in JSON Schema and Zod)
- Handler methods should be named `handle<PascalCaseName>` (e.g. `handleManagePackages`)
- If a tool needs file uploads, use `this.apiClient.uploadFile()` — see `manage_packages` handler for the pattern
- Update `README.md` tool count and table if adding a brand new tool