Ch7. Tools, Approval, Connections

Tools are typed actions the model can request. The most important operational fact is that authored tool execute runs in the app runtime. If it can access secrets or internal APIs, treat it as privileged code.

Tool Structure

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Return mock weather data for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});

Standards:

• description is model-facing routing text
• inputSchema is a control surface
• execute must tolerate replay and retries
• returned data may enter history and telemetry, so minimize it

Minimize Model-visible Output

Use toModelOutput when hooks/channels need rich output but the model should see only a summary.

toModelOutput(output) {
  return {
    type: "text",
    value: `Report ${output.id}: risk ${output.riskLevel}.`,
  };
}

This prevents CRM rows, audit payloads, pricing tables, and PII from being copied into later model context.

Approval Policy

import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";
import { z } from "zod";

export default defineTool({
  description: "Refund a customer charge.",
  inputSchema: z.object({
    chargeId: z.string(),
    amount: z.number().positive(),
  }),
  needsApproval: always(),
  async execute(input) {
    return refundCharge(input);
  },
});

Input-based Approval

needsApproval: ({ toolInput }) => {
  const amount = Number(toolInput?.amount ?? 0);
  return amount > 1000;
}

Keep business policy in pure functions under agent/lib/ and unit test it. Do not hide large policy logic inside tool definitions.

HITL Is Durable Parking

When approval is required, Eve emits input.requested and parks the session in session.waiting. The process is not held open. The session resumes when the answer arrives.

Connections

Connections expose external MCP or OpenAPI tools that you do not author.

The model discovers them through connection__search and calls qualified names.

import { defineMcpClientConnection } from "eve/connections";
import { once } from "eve/tools/approval";

export default defineMcpClientConnection({
  url: "https://mcp.linear.app/sse",
  description: "Linear workspace: issues, projects, cycles, and comments.",
  auth: {
    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
  },
  tools: { allow: ["search_issues", "get_issue"] },
  approval: once(),
});

Tokens Stay Out Of The Model

Connection tokens are resolved in the app runtime and injected into outbound requests. They do not become model context. This is a major safety property, but scope still matters.

Tool Auth vs Connection Auth vs Route Auth

Route auth does not automatically make tool or connection scopes safe.

ask_question vs Approval

All use the same durable input.requested pause protocol, but their intent is different.

Tool Design Checklist