Tools and Tool Packages
Lesson 4: Tools and Tool Packages
Tools are where your agent stops being a chatbot and starts doing work. They are also, in practice, where most production quality is won or lost. A tool is a typed contract the model can invoke, and the SDK's job is to route the call into your handler and send the result back. Your job is to make each tool's contract honest, narrow, and cheap.
Anatomy of a tool
import { z } from "zod";
import { CopilotClient, defineTool } from "@github/copilot-sdk";
const session = await client.createSession({
model: "gpt-5",
tools: [
defineTool("lookup_issue", {
description: "Fetch issue details from our tracker",
parameters: z.object({
id: z.string().describe("Issue identifier"),
}),
handler: async ({ id }) => {
const issue = await fetchIssue(id);
return issue;
},
}),
],
});
Four required pieces: a globally unique name, a description the model reads, a parameters schema, and a handler. Zod is the ergonomic path โ the SDK converts it to JSON Schema for the model and validates arguments before your handler runs, so your handler receives typed, validated input. A raw JSON Schema object works too if you prefer not to depend on Zod.
Your handler is called as (args, invocation). The second argument is the one people forget exists, and it is where the production-useful metadata lives:
invocation field | Use it for |
|---|---|
sessionId | Scoping a database transaction, log correlation, tenant lookup |
toolCallId | Correlating your logs with tool.execution_start/complete events and audit trails |
toolName | Generic middleware across all your tools |
arguments | The raw, pre-validation argument object |
traceparent / tracestate | Continuing the distributed trace โ see Lesson 9 |
Return values: the taxonomy that drives behaviour
You can return a plain string, any JSON-serialisable value (auto-wrapped), or a structured result object. Only the structured form lets you tell the runtime what kind of outcome this was โ which matters, because the runtime treats them differently:
| What you return | Interpreted as |
|---|---|
"some text" | Success |
| Any JSON-serialisable object | Success, auto-wrapped |
{ textResultForLlm, resultType } | Structured result |
undefined | Empty success โ not an error |
| Throwing | Failure, with your error message sent to the model |
The resultType discriminator has four supported values plus one reserved:
resultType | Meaning | Consequence |
|---|---|---|
"success" | Worked | Normal path; onPostToolUse fires |
"failure" | The tool ran but did not achieve its goal | onPostToolUseFailure fires (not onPostToolUse) |
"rejected" | The call was refused before execution | Does not fire the failure hook |
"denied" | Permission was refused | Does not fire the failure hook |
"timeout" | Reserved โ recognised but does not currently fire the failure hook | โ |
undefined is the sharpest edge in this lesson. In a tool whose purpose is to report (a validator, a linter, a check), returning nothing produces an empty success โ the model concludes the check passed. Silent false-passes in agent pipelines almost always trace back to a handler with no explicit return on the happy path. Always return a string, even if it is just "ok".
textResultForLlm the model can reason about, and rich structure for your observability.
Tool-level flags worth knowing
| Flag | Effect | When to reach for it |
|---|---|---|
overridesBuiltInTool: true | Allows you to replace a built-in CLI tool of the same name | You want project-specific validation on edit_file / read_file |
skipPermission: true | This tool executes without triggering a permission prompt | Provably read-only, no-side-effect lookups |
defer: "auto" | "never" | Whether the tool may be loaded lazily via tool search instead of always pre-loaded (default "auto") | "never" for tools that must always be visible |
isTerminal: true | Successful completion ends the current agent turn | Context-clearing / handoff tools (Lesson 3) |
Registering a tool whose name collides with a built-in throws unless you explicitly opt in โ a deliberate guardrail, since silently shadowing read_file would be a nasty surprise:
defineTool("edit_file", {
description: "Custom file editor with project-specific validation",
parameters: z.object({ path: z.string(), content: z.string() }),
overridesBuiltInTool: true,
handler: async ({ path, content }) => {
/* your logic */
},
});
There is one schema quirk: an apply_patch override may declare a string schema. The model still sees a required input property, but the runtime restores the declared scalar shape before dispatch โ both a Zod-inferred handler and invocation.arguments receive the patch text as a string. String-schema apply_patch overrides cannot contain JSON Schema references; use an object schema if you need $ref.
Deferral is a prompt-budget decision
Every tool definition you register occupies space in the model's context on every call. With dozens of tools that becomes real money and a real source of selection errors. defer: "auto" (the default) marks a tool as eligible for tool search โ the model can find and load it on demand rather than carrying it always.
defineTool("lookup_issue", {
description: "Fetch issue details",
parameters: z.object({ id: z.string() }),
defer: "auto",
handler: async ({ id }) => { /* ... */ },
});
availableTools to allowlist only what a session needs; (2) defer: "auto" so long-tail tools are searchable rather than always-present; (3) defaultAgent.excludedTools to hide heavy tools from the main agent and force delegation (Lesson 8). A tool with a vague description is worse than a missing tool โ the model pays the token cost and still selects it wrongly. Descriptions are prompt engineering that runs on every single call.
Replacing tools on a live session
You can swap a session's tool set without recreating it โ the pattern behind a page-aware assistant that offers only the tools the current view provides. The call replaces this client's entire tool set; built-in, MCP, plugin, and other clients' tools are untouched. Pass an empty array to remove all of yours.
import { CopilotClient, approveAll, defineTool } from "@github/copilot-sdk";
import { z } from "zod";
const client = new CopilotClient();
const session = await client.createSession({ onPermissionRequest: approveAll });
const searchIssues = defineTool("search_issues", {
description: "Search the issues shown on the current page",
parameters: z.object({ query: z.string().describe("Search text") }),
handler: async ({ query }) => findIssues(query),
});
await session.setTools([searchIssues]); // supply only the current page's tools
await session.setTools([]); // remove all of this client's tools
The semantics are precise and worth internalising, because each line is a production incident you can avoid:
| Aspect | Behaviour |
|---|---|
| Model visibility | The new tools appear from the agent's next model request โ which can be part of a turn already in progress |
| Handlers | Take effect as soon as the runtime accepts the replacement; calls already running finish on their original handlers |
| Rejection | Invalid names, or names another connected client already supplies โ replaces nothing, previous set stays live |
| Ordering | Concurrent replacements apply one at a time, in order |
| Cancellation | Cancelling after the request is sent stops only the wait โ an accepted replacement still takes effect |
session.idle โ or abort first. Replacing a tool's handler under the same name is safe during a turn.
Packaging tools: the module-as-factory pattern
A "tool package" is just a module that exports a factory returning Tool[]. The value of the pattern is that it forces three good decisions: explicit dependencies, no module-level state, and one place to document the budget each tool spends.
// tools/orders.ts
import { defineTool, type Tool } from "@github/copilot-sdk";
import { z } from "zod";
export interface OrderToolDeps {
orders: OrderRepository; // injected, not imported
logger: Logger;
maxRows: number; // budget knob, explicit
}
export function orderTools(deps: OrderToolDeps): Tool[] {
const { orders, logger, maxRows } = deps;
return [
defineTool("orders_lookup", {
description:
"Look up a single order by its ID. Returns status, total, and item count. " +
"Does not return line items โ use orders_items for that.",
parameters: z.object({
orderId: z.string().describe("Order identifier, e.g. ord_1234"),
}),
handler: async ({ orderId }, invocation) => {
logger.info({ orderId, toolCallId: invocation.toolCallId }, "orders_lookup");
const order = await orders.find(orderId);
if (!order) {
return {
textResultForLlm: `No order found with id ${orderId}.`,
resultType: "failure",
};
}
// Return a PROJECTION, not the whole record.
return {
textResultForLlm:
`Order ${order.id}: ${order.status}, total ${order.total}, ` +
`${order.itemCount} items, placed ${order.placedAt}.`,
resultType: "success",
};
},
}),
defineTool("orders_items", {
description:
"List the line items of an order. Paginated โ returns at most `limit` items " +
"and reports whether more exist.",
parameters: z.object({
orderId: z.string(),
limit: z.number().int().min(1).max(50).default(20),
}),
handler: async ({ orderId, limit }) => {
const items = await orders.items(orderId, { limit });
return {
textResultForLlm:
items.map((i) => `- ${i.sku} x${i.qty} @ ${i.price}`).join("\n") +
(items.length === limit ? "\n(More items exist; call again with an offset.)" : ""),
resultType: "success",
};
},
}),
];
}
Then at the call site, the session becomes a composition of packages:
const session = await client.createSession({
onPermissionRequest: permissionHandler,
availableTools: ["custom:orders_lookup", "custom:orders_items"],
tools: [
...orderTools({ orders: orderRepo, logger, maxRows: 20 }),
...catalogTools({ catalog: catalogRepo }),
],
});
Nine rules for tools that hold up in production
| # | Rule | Why |
|---|---|---|
| 1 | Never console.log() in a tool handler | stdout is reserved for JSON-RPC โ logging to it corrupts the protocol. Use a logger writing to stderr or your log sink. |
| 2 | Return a projection, not the raw record | Raw payloads land in context and trigger compaction. Return what the model needs to decide. |
| 3 | Paginate anything unbounded | An unpaginated list tool is an unbounded context injection with a friendly name. |
| 4 | State the negative contract in the description | "Does not return line items" prevents a whole class of wrong-tool selection. |
| 5 | Use resultType: "failure" for "ran but did not achieve it" | Distinguishes a lookup miss from an infrastructure error, and routes to the right hook. |
| 6 | Keep handlers stateless | In-memory tool state is not persisted; a resumed session loses it. |
| 7 | Inject dependencies as a factory | Makes the package unit-testable without a live session, and swappable per tenant. |
| 8 | Name tools with a stable prefix | orders_*, catalog_* makes allowlists (availableTools) and audit greps tractable. |
| 9 | Correlate with invocation.toolCallId | Your logs then join cleanly to tool.execution_start / tool.execution_complete. |
@github/copilot-sdk/extension with joinSession()) for registering tools and hooks into the CLI itself rather than into your process. Same hook names and result shapes, but hard constraints: only immediate subdirectories are scanned, each must contain extension.mjs (TypeScript is not supported), project extensions shadow user extensions on name collision, tool-name collisions are fatal (the second extension fails to load), and extensions reload on /clear so all in-memory state is lost. Use it to ship capability into an existing CLI; use defineTool when you own the process.
Debugging tools
Two failure modes cover most of it. Tools the model never calls: almost always a description problem โ the model cannot tell what it is for, or the tool is deferred and never surfaced. Tools that call but misbehave: watch tool.execution_start (carries toolCallId, toolName, arguments) and tool.execution_complete (carries success, result, error) โ that pair is your per-call ground truth, and it includes the validated arguments the model actually sent, which is frequently not what you assumed.
๐ง Knowledge Check
1. A validation tool returns nothing on the happy path. What does the runtime conclude?
2. Which hook fires when a tool returns resultType: "failure"?
3. You want to remove a tool from a busy session. What is the safe sequence?