create-client-tool
cognitedata/builder-skills
Scaffold an AtlasTool for in-app useAtlasChat UI integration.
What is create-client-tool?
Creates a client-side tool that the Atlas Agent can invoke to execute browser logic, validate arguments with TypeBox schemas, and return results. Use this when you have an approved in-app useAtlasChat UI; for EOS sidebar tools, use integrate-fusion-agent instead.
- Generates an AtlasTool with TypeBox parameter validation
- Enables agent-driven invocation of browser-side logic (charts, state, UI panels, navigation)
- Returns structured output and details for agent and UI rendering
- Provides step-by-step scaffolding from schema definition to useAtlasChat wiring
- Includes TypeBox quick reference for common parameter types
How to install create-client-tool
npx skills add https://github.com/cognitedata/builder-skills --skill create-client-tool- Vendored src/atlas-agent/ folder from integrate-atlas-chat skill
- @sinclair/typebox package installed
- An existing useAtlasChat integration in the app
How to use create-client-tool
- 1.Read the file where useAtlasChat is called to understand the tools array location and naming conventions
- 2.Define your tool using Type from @sinclair/typebox for parameters schema and an execute async function
- 3.Add the tool to the useAtlasChat tools array in your component or hook
- 4.Optionally render tool results by accessing message.toolCalls in your message list component
Use cases
- Add a tool that fetches and displays chart data when the agent requests visualization
- Create a navigation tool that the agent can call to route to specific app pages
- Build a local-state query tool that returns filtered data based on agent parameters
- Implement a UI panel toggle tool that the agent controls based on conversation context
- Frontend engineers building Atlas Agent integrations
- Teams with approved in-app useAtlasChat implementations
- Developers extending agent capabilities with client-side logic
create-client-tool FAQ
Use create-client-tool for in-app useAtlasChat UI tools that run in the browser. Use integrate-fusion-agent for EOS sidebar tools and server-side agent actions.
output is a plain text string sent back to the agent for reasoning; details is structured data available on message.toolCalls for the UI to render.
Wrap any TypeBox schema with Type.Optional(), e.g., Type.Optional(Type.Number()).
Define it near your atlas-agent folder (typically src/tools/ or src/) and adjust import paths accordingly if nested deeper.
Full instructions (SKILL.md)
Source of truth, from cognitedata/builder-skills.
name: create-client-tool description: "Scaffolds an AtlasTool for an already-approved in-app useAtlasChat UI. For EOS sidebar tools, use integrate-fusion-agent (createAgentAction) instead. Triggers: AtlasTool, useAtlasChat tool, in-app atlas client tool." allowed-tools: Read, Glob, Grep, Edit, Write metadata: argument-hint: "[tool-name] [brief description of what it does]"
Create a Client Tool
Scaffold an AtlasTool named $ARGUMENTS. If the app has no approved in-app useAtlasChat, implement a Fusion action via integrate-fusion-agent instead.
Prerequisite: vendored src/atlas-agent/ and @sinclair/typebox from integrate-atlas-chat.
Background
Client tools let the Atlas Agent invoke browser-side logic — charts, local state, UI panels, navigation. The agent decides when to call; the app executes and returns a result.
- Agent responds with a
clientToolaction - TypeBox validates the arguments
execute()runs in the browser and returns{ output, details }output(string) is sent back to the agentdetailsis available onmessage.toolCallsfor the UI to render
Step 1 — Understand the codebase
Before writing anything, read:
- The file where
useAtlasChatis called (oftensrc/App.tsxor a chat hook) to find wheretoolsis passed — imports are typically from./atlas-agent/reactafterintegrate-atlas-chat - Any existing tool definitions to match the file/naming conventions
Step 2 — Define the tool
Use Type from @sinclair/typebox for the parameters schema (compile-time types + runtime validation).
import { Type } from "@sinclair/typebox";
import type { AtlasTool } from "./atlas-agent/types";
export const myTool: AtlasTool = {
name: "my_tool", // snake_case — this is what the agent uses to invoke it
description:
"One sentence describing what this tool does and when the agent should call it.",
parameters: Type.Object({
exampleParam: Type.String({ description: "What this param is for" }),
optionalNum: Type.Optional(Type.Number({ description: "..." })),
}),
execute: async (args) => {
return {
output: "Plain text summary sent back to the agent",
details: {
// Any structured data you want available in the UI via message.toolCalls
},
};
},
};
Adjust the ./atlas-agent/... path if the tool file is not directly under src/ next to the atlas-agent folder (for example ../atlas-agent/types from src/tools/).
TypeBox quick reference
| Schema | Usage |
|---|---|
Type.String() | string |
Type.Number() | number |
Type.Boolean() | boolean |
Type.Literal("foo") | exact value |
Type.Union([Type.Literal("a"), Type.Literal("b")]) | enum |
Type.Array(Type.String()) | string[] |
Type.Object({ ... }) | object |
Type.Optional(...) | mark any field optional |
Always add a description on the tool and on each parameter — the agent uses those strings.
Step 3 — Wire into useAtlasChat
Find the useAtlasChat call and add the tool to the tools array:
const { messages, send, ... } = useAtlasChat({
client: isLoading ? null : sdk,
agentExternalId: AGENT_EXTERNAL_ID,
tools: [myTool], // add here
});
Step 4 — Render tool results (if needed)
If the tool returns structured details, render them in the message list.
message.toolCalls is a ToolCall[] — one entry per tool call (client-side and server-side) in call order.
{msg.toolCalls?.map((tc, i) => (
// tc.name — tool name
// tc.output — the string sent back to the agent
// tc.details — your structured data (cast to your known shape)
<MyToolOutput key={i} data={tc.details as MyToolDetails} />
))}
Related skills
More from cognitedata/builder-skills and the wider catalog.
