Custom tools

Give the agent a function on your server, connect it, and check that it works.

import { defineConfig, 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.",
      input: {
        orderNumber: p.string("The order number, like ORD-1042."),
      },
      async execute({ orderNumber }, { visitor }) {
        if (!visitor.verified) return { ok: false, reason: "not_signed_in" };
        const order = await db.orders.find(visitor.externalId, orderNumber);
        if (!order) return { found: false };
        return { found: true, status: order.status, eta: order.eta };
      },
    },
  },
});

import { median } from "@mediansh/agent-tools";
import config from "@/median.config";

export const { GET, POST } = median(config);

Set up a tool

npm install @mediansh/agent-tools

pnpm add @mediansh/agent-tools

yarn add @mediansh/agent-tools

bun add @mediansh/agent-tools

MEDIAN_KEY=median_key_...

import { median } from "@mediansh/agent-tools";
import config from "@/median.config";

export const { GET, POST } = median(config);

import { median } from "@mediansh/agent-tools";
import config from "./median.config";

const { GET, POST } = median(config);

export default {
  async fetch(request: Request): Promise<Response> {
    const { pathname } = new URL(request.url);
    if (pathname === "/api/median") {
      if (request.method === "GET") return GET(request);
      if (request.method === "POST") return POST(request);
    }
    return new Response("Not found", { status: 404 });
  },
};

curl -H "Authorization: Bearer $MEDIAN_KEY" https://acme.com/api/median

{
  "connected": true,
  "endpoint": "https://acme.com/api/median",
  "tools": 1,
  "message": "Connected. Median is syncing 1 tool."
}

Connect a route

There are three ways to connect a route. Connecting a URL that is already connected syncs it again.

The dashboard and the CLI need an Admin or Owner and an existing Median key. Without a key they fail with “Create a Median key in Settings under API before connecting tools.”

Your route checks every call against the MEDIAN_KEY on your server. If that key is not the one the endpoint signs with, syncs fail with “The endpoint refused the signature.” After you rotate the key, open the route again.

The bearer header is required on every connect, including on localhost and with MEDIAN_TOOLS_URL set. Without it the route answers 401 unauthorized and connects nothing. Keep the key in server or CI secrets, never in browser code or a URL.

Set the public address

Without a setting, the route registers the URL the request arrived at, minus the query string. Set MEDIAN_TOOLS_URL, or the url option, when the server sits behind a proxy or a tunnel, or answers on more than one hostname.

MEDIAN_TOOLS_URL=https://acme.com

An origin gets the route’s path added, so one value serves several routes. A value with a path is used as written for every route. A value that is not a URL answers 400 median_endpoint_unknown.

URL rules

Check it synced

The tools count in the connect response is the number of tools in your local config. The sync runs after the response, so check the result:

median tools list

It lists each endpoint with its status and last error, and each tool with its risk and whether it is on.

On Agent → Tools, each row under Endpoints shows one of these:

A failed row keeps showing Sync failed until a sync succeeds, even while a new one runs.

Tool errors lists every sync message and its fix.

When a sync runs

Tools you deploy reach the next new conversation with no extra step. On-demand syncs are rate limited. See Rate limits. With more than one endpoint, median tools endpoint sync needs --url.

A sync changes the tool list like this:

• New tools arrive switched on.
• A tool’s on or off switch survives later syncs.
• A tool that leaves the manifest is deleted.
• A failed sync keeps the last good tool set.

After a sync, each tool gets a readable name and summary on Agent → Tools. The page shows Writing tool descriptions… while that runs. The agent still reads your description.

Risk levels

risk decides what happens when the agent calls a tool.

• Median adds the confirmation or sign-off instruction to your description. Do not write it yourself.
• medium depends on the agent following its instructions. Use reviewed or high for any call that must not run unchecked.
• A teammate can also run any switched-on tool from a conversation, at any risk, with no sign-off.

How tool calls run covers approvals, reviews and per-turn limits. Approvals and tool runs covers deciding them in the inbox.

The agent already searches your knowledge base. Keep documentation and policies there, not in a tool. Built-in abilities lists what the agent does without your code.

Test a tool

Call a tool with no conversation behind it:

median tools test orderStatus --input '{"orderNumber":"ORD-1042"}' --as user_123

• The call goes to the URL of the endpoint that serves the tool, signed the way the agent signs. Nothing appears in the inbox.
• Without --as or --conversation, the visitor is unverified and has no id. Run an account tool this way once to check that it refuses.
• context.toolCallId is test_ and a UUID. context.conversationId is the same value, or the real thread’s id with --conversation.
• context.approvedBy is "A test from the CLI".
• The command exits with code 1 when ok is false, including refusals.
• It reaches switched-on tools only, and needs an Admin or Owner. See Roles.

A synced manifest does not prove a tool works. Test each tool with real input and read the fields it returns.

To run a tool on a real conversation as a teammate, use median tools run <conversation> <tool>. See How tool calls run and the CLI reference.

Local development

Median calls your route from the cloud, so a local route needs a tunnel.

ngrok http 3000

MEDIAN_KEY=median_key_...
MEDIAN_TOOLS_URL=https://your-tunnel.ngrok.app

curl -H "Authorization: Bearer $MEDIAN_KEY" http://localhost:3000/api/median

A new tunnel hostname is a new endpoint. Its tools clash with the old endpoint’s tools of the same name, and the sync fails with The tool name "orderStatus" already comes from <old url>. Tool names have to be unique across every endpoint. Remove the old endpoint first, or use Change endpoint in its menu. A fixed tunnel domain avoids this.

A plain http://localhost URL does not work against Median’s cloud. The sync fails with “http://localhost:3000 is this deployment’s own machine, not yours.”

Next steps