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 fieldUse it for
sessionIdScoping a database transaction, log correlation, tenant lookup
toolCallIdCorrelating your logs with tool.execution_start/complete events and audit trails
toolNameGeneric middleware across all your tools
argumentsThe raw, pre-validation argument object
traceparent / tracestateContinuing 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 returnInterpreted as
"some text"Success
Any JSON-serialisable objectSuccess, auto-wrapped
{ textResultForLlm, resultType }Structured result
undefinedEmpty success โ€” not an error
ThrowingFailure, with your error message sent to the model

The resultType discriminator has four supported values plus one reserved:

resultTypeMeaningConsequence
"success"WorkedNormal path; onPostToolUse fires
"failure"The tool ran but did not achieve its goalonPostToolUseFailure fires (not onPostToolUse)
"rejected"The call was refused before executionDoes not fire the failure hook
"denied"Permission was refusedDoes not fire the failure hook
"timeout"Reserved โ€” recognised but does not currently fire the failure hookโ€”
Returning 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".
Structured results are preserved, not stringified. When you return a result object with metadata (including tool telemetry), the SDK sends it over RPC as an object rather than flattening it to text โ€” so metadata survives for your own instrumentation without leaking into the model's view. Design your tools to return both: a short textResultForLlm the model can reason about, and rich structure for your observability.

Tool-level flags worth knowing

FlagEffectWhen to reach for it
overridesBuiltInTool: trueAllows you to replace a built-in CLI tool of the same nameYou want project-specific validation on edit_file / read_file
skipPermission: trueThis tool executes without triggering a permission promptProvably 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: trueSuccessful completion ends the current agent turnContext-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 }) => { /* ... */ },
});
Token angle: think of the tool surface as a standing tax paid on every turn. Three levers reduce it: (1) 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:

AspectBehaviour
Model visibilityThe new tools appear from the agent's next model request โ€” which can be part of a turn already in progress
HandlersTake effect as soon as the runtime accepts the replacement; calls already running finish on their original handlers
RejectionInvalid names, or names another connected client already supplies โ†’ replaces nothing, previous set stays live
OrderingConcurrent replacements apply one at a time, in order
CancellationCancelling after the request is sent stops only the wait โ€” an accepted replacement still takes effect
Never remove a tool mid-turn. A model request already in flight was made with the old tool list, so the agent can still call a tool you just removed. The session will not answer that call (another client might legitimately supply the same name), so it stays pending until the turn is aborted. Replace tools while the session is idle โ€” for example after 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

#RuleWhy
1Never console.log() in a tool handlerstdout is reserved for JSON-RPC โ€” logging to it corrupts the protocol. Use a logger writing to stderr or your log sink.
2Return a projection, not the raw recordRaw payloads land in context and trigger compaction. Return what the model needs to decide.
3Paginate anything unboundedAn unpaginated list tool is an unbounded context injection with a friendly name.
4State the negative contract in the description"Does not return line items" prevents a whole class of wrong-tool selection.
5Use resultType: "failure" for "ran but did not achieve it"Distinguishes a lookup miss from an infrastructure error, and routes to the right hook.
6Keep handlers statelessIn-memory tool state is not persisted; a resumed session loses it.
7Inject dependencies as a factoryMakes the package unit-testable without a live session, and swappable per tenant.
8Name tools with a stable prefixorders_*, catalog_* makes allowlists (availableTools) and audit greps tractable.
9Correlate with invocation.toolCallIdYour logs then join cleanly to tool.execution_start / tool.execution_complete.
There is a second packaging surface: CLI extensions. The SDK also ships an extension entry point (@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?

Further Reading