Config reference

import { defineConfig, navigation, p } from "@mediansh/agent-tools";
import { db } from "@/lib/db";

export default defineConfig({
  tools: {
    orderStatus: {
      description: "Look up the status of one of the customer's orders.",
      risk: "low",
      input: { orderNumber: p.string("The order number.") },
      async execute({ orderNumber }, context) {
        if (!context.visitor.verified) return { ok: false, reason: "not_signed_in" };
        const order = await db.orders.find(context.visitor.externalId, orderNumber);
        return order ? { status: order.status } : { found: false };
      },
    },
  },
  plugins: [navigation({ exclude: ["/admin/**"] })],
  diagnostics: async () => ({ version: process.env.GIT_SHA }),
});

defineConfig

defineConfig returns a MedianConfig with your tools' defaults filled in. Pass it to median() or createMedianHandler().

Tool fields

Median adds a line to the description for medium, reviewed and high tools, telling the agent to ask first or that the call waits for sign-off. Do not write that yourself. Risk levels has what each level does.

Names

Input builders

Every builder takes an optional description as its last argument. .optional() makes a field optional in TypeScript and in the schema. Inputs are flat. A tool takes up to 20 fields, and its schema may be up to 8,000 characters as JSON.

The route validates input before execute runs. There is no coercion, so "12" is not a number. null counts as absent. Numbers must be finite. The first failure answers 400 invalid_input, and the agent is told its input was wrong so it can fix it and call again:

What execute receives

execute(input, context). input is typed from your input declaration.

Visitor fields

Authorize on externalId, and only when verified is true.

approvedBy and ids

approvedBy and toolCallId for each way a call can run are in What your endpoint receives.

Treat toolCallId and conversationId as opaque strings. Median sends each call once and does not retry it. A teammate running the tool again, or the agent calling it again, is a new call with a new toolCallId. Pass toolCallId as the idempotency key to any system you write to, so your own retries of one call apply once.

Return values

Return any JSON value. The route answers { "result": ... }, and undefined becomes null.

Refusals

A result is a refusal when it has any of these:

return { ok: false, reason: "not_signed_in", detail: "Sign in to see orders." };

The agent reads reason and detail as the tool's own words and is told not to retry. Without a reason it reads tool_refused. outcome: "unknown" also tells it the action may have completed and to check its state before retrying. A refusal's medianNavigateTo and medianHighlight are ignored. median tools test reports a refusal as ok: false.

Other results, such as { found: false }, are data. Use one refusal shape across your tools.

Errors

The table covers calls the agent makes itself. When an approved call fails, the conversation shows a line saying it did not run, with the error, and the agent treats the action as not done.

Tool errors lists every error code with its fix.

Plugins

A plugin is a named bundle of tools.

type MedianPlugin = {
  name: string;
  tools: Record<string, Tool>;
};

• Plugin tools are added first, then yours.
• Plugin tools get no defaults. risk and input are required.
• navigation() is the plugin this package ships. See Pages and highlights.

Split tools across files by giving each module its own defineConfig and passing its tools as a plugin:

import { defineConfig } from "@mediansh/agent-tools";
import account from "./median/account";
import orders from "./median/orders";

export default defineConfig({
  plugins: [
    { name: "account", tools: account.tools },
    { name: "orders", tools: orders.tools },
  ],
});

A name clash throws when the route module loads:

When the config is checked

At load, the route module throws with a message naming the tool. At sync, the endpoint shows Sync failed and the reason, and the agent keeps the last good tool set.

Server diagnostics

diagnostics sits beside tools. It runs when a report is filed on Signal and at no other time. What it returns is attached to the report, next to what the customer's browser collected.

export default defineConfig({
  diagnostics: async () => ({
    version: process.env.GIT_SHA,
    database: (await db.ping()) ? "up" : "down",
    queueDepth: await jobs.depth(),
  }),
  tools: {
    // ...
  },
});

The report is filed either way. Context and diagnostics covers the browser side.

Route handlers

median()

median(config, options?): { GET, POST }

config is a defineConfig result or the same object inline. GET without a signature connects the route. A signed GET answers the manifest. POST runs a tool.

createMedianHandler()

createMedianHandler(config, options?): (request: Request) => Promise<Response>

One handler for frameworks that want a single function. It takes a defineConfig result and the key and toleranceMs options.

Connect a createMedianHandler() route from Agent → Tools or with median tools endpoint add.

Environment variables

Requests the route answers

Errors wear { "error": { "code", "message" } }. Every response sets Cache-Control: private, no-store.

Tool endpoint reference has the wire format.

Limits

Per-turn and approval limits are in How tool calls run.

Runtimes

The handlers use only the Web Request, Response and Web Crypto APIs. They run on Node, Bun, Deno, Next.js route handlers on either runtime, and edge platforms. navigation() reads your routes from disk, which needs Node 20.16 or later, or Bun. On edge runtimes pass routes.

Package exports

The package also exports these types: MedianConfig, MedianConfigInput, MedianPlugin, DiagnosticsCollector, NavigationOptions, Field, InferInput, MedianHandlerOptions, MedianOptions, MedianIdentityOptions, MedianIdentityResolver, MedianIdentityRoute, MedianIdentityUser, MedianVisitor, ToolContext, ToolRisk.