# Tools and context

> Give a Slack or Teams agent typed application actions and the right context for each managed turn.

Channel tools let your agent call application code while it works in Slack or
Teams. Context gives the agent information it should consider without exposing
another callable action.

Install the schema library used in these examples:

```bash title="Terminal"
npm install zod
```

## Add a channel-level tool [#add-a-channel-level-tool]

Use `defineChannelTool` for actions that are available in every conversation.
The parameter schema becomes the tool's JSON schema and types the handler.

```ts title="tools.ts"
import { defineChannelTool } from "@copilotkit/channels";
import { z } from "zod";

export const getIncident = defineChannelTool({
  name: "get_incident",
  description: "Read the current status of an incident by its id.",
  parameters: z.object({
    incidentId: z.string().describe("Incident id, for example INC-421"),
  }),
  async handler({ incidentId }) {
    const incident = await incidents.get(incidentId);
    return incident; // objects are serialized for the model
  },
});
```

Register it when you create the Channel:

```ts title="channel.ts"
import { createChannel } from "@copilotkit/channels";
import { makeAgent } from "./agent.js";
import { getIncident } from "./tools.js";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const channel = createChannel({
  name: required("CHANNEL_CODE"),
  identifyUser: "platform",
  agent: makeAgent,
  tools: [getIncident],
});
```

Return information the model can act on:

- Return raw objects or arrays for data tools.
- Return a short confirmation when the handler already posted UI.
- Return or throw the real failure reason so the model can recover.
- Do not manually `JSON.stringify` successful data.

## Add stable context [#add-stable-context]

Channel context is sent on every agent run:

```ts title="channel.ts"
import { createChannel } from "@copilotkit/channels";
import { makeAgent } from "./agent.js";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const channel = createChannel({
  name: required("CHANNEL_CODE"),
  identifyUser: "platform",
  agent: makeAgent,
  context: [
    {
      description: "Support policy",
      value:
        "Never disclose credentials. Escalate Sev-1 incidents immediately.",
    },
    {
      description: "Response style",
      value: "Use short paragraphs and put the next action first.",
    },
  ],
});
```

Keep this list stable and small. Fetch frequently changing data through a tool
instead of embedding stale snapshots in every prompt.

## Use provider and user context for one turn [#use-provider-and-user-context-for-one-turn]

On a managed Channel, `message.platform`, `thread.platform`, and a
channel-level tool's `ctx.platform` report the native origin (`"slack"` or
`"teams"`).

Add native context when you run the agent:

```ts title="channel.ts"
channel.onMessage(async ({ thread, message }) => {
  await thread.runAgent({
    context: [
      { description: "Originating platform", value: message.platform },
      {
        description: "Requesting user",
        value: message.user?.name ?? "Unidentified application user",
      },
    ],
  });
});
```

If a tool must be scoped to the current person, define it inside the handler and
pass it for that run. Its closure captures the trusted inbound identity:

```ts title="channel.ts"
channel.onMessage(async ({ thread, message }) => {
  const user = message.user;
  if (!user) return;
  const listMyApprovals = defineChannelTool({
    name: "list_my_approvals",
    description: "List approvals assigned to the requesting user.",
    parameters: z.object({}),
    async handler() {
      return approvals.forApplicationUser(user.id);
    },
  });

  await thread.runAgent({
    prompt: message.text,
    tools: [listMyApprovals],
  });
});
```

Treat provider actor IDs as external identifiers. Use the resolved application
`user` for personal product data, and check it for `null` before a write.

## Render a tool result as native UI [#render-a-tool-result-as-native-ui]

A tool can post a portable JSX message and return a short acknowledgement to
the model:

```tsx title="tools.tsx"
import { defineChannelTool } from "@copilotkit/channels";
import { Header, Message, Section } from "@copilotkit/channels/ui";
import { z } from "zod";

export const showIncident = defineChannelTool({
  name: "show_incident",
  description: "Display an incident summary in the conversation.",
  parameters: z.object({
    id: z.string(),
    status: z.string(),
    summary: z.string(),
  }),
  async handler({ id, status, summary }, { thread }) {
    await thread.post(
      <Message>
        <Header>{`${id} · ${status}`}</Header>
        <Section>{summary}</Section>
      </Message>,
    );
    return `Displayed ${id}.`;
  },
});
```

Enable Channels JSX before using this example:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@copilotkit/channels"
  }
}
```

The portable message is rendered as a Microsoft Teams Adaptive Card before
Intelligence sends it to the conversation.

To post a result as an image, see
[Posting JSX as images](/teams/posting-jsx-as-images).

## Where MCP belongs [#where-mcp-belongs]

Connect MCP servers to the selected agent backend. The Channels SDK forwards
channel tools over AG-UI alongside the tools already exposed by that agent, so
you do not need a second channel-specific MCP transport. Start with
[MCP tools](/agentic-protocols/mcp), then use `defineChannelTool` only for
actions that need the current channel conversation.

To check the tool, mention the bot and ask for the status of INC-421. The agent
calls `get_incident` and replies with the incident status.

Continue with [interactive messages and approvals](/teams/interactive), or
use the [Channel API reference](/reference/channels/classes/Channel).
