Tool Polish

defineTool() exposes three additional fields in v2.0 that materially improve reliability and cost.

1. `strict: true` — guaranteed valid arguments

import { defineTool } from "@agentium/core";
import { z } from "zod";

const lookup = defineTool({
  name: "lookupOrder",
  description: "Look up an order by ID.",
  parameters: z.object({ orderId: z.string() }),
  strict: true,                              // ← new
  execute: async ({ orderId }) => { /* ... */ },
});

When strict: true:

additionalProperties: false is appended to the generated JSON Schema, so the LLM cannot send junk extra keys.
For OpenAI-family models, strict: true flows through to the API’s structured-output mode, which guarantees the model’s tool call is valid JSON matching your schema (no retries, no parse errors).

When to use: any tool whose schema you want to enforce hard — DB queries, payment operations, anything where “the LLM made up a field” would be embarrassing. Trade-offs:

OpenAI strict mode disables certain features (anyOf, default values on optional fields). If your schema fails to compile in strict mode, drop the flag.
Anthropic / Google providers ignore the strict flag at the API level but the JSON Schema is still tightened, which the model usually respects.

2. `inputExamples` — N-shot demonstrations

const search = defineTool({
  name: "search",
  description: "Search the web for current information.",
  parameters: z.object({
    query: z.string(),
    timeRange: z.enum(["day", "week", "month", "year", "all"]).optional(),
  }),
  inputExamples: [
    { query: "node 22 release notes" },
    { query: "OpenAI o1 pricing", timeRange: "month" },
    { query: "rust async tutorial", timeRange: "year" },
  ],
  execute: async ({ query, timeRange }) => { /* ... */ },
});

The framework appends a formatted examples section to the tool description that the LLM sees:

Search the web for current information.

Examples:
1. {"query":"node 22 release notes"}
2. {"query":"OpenAI o1 pricing","timeRange":"month"}
3. {"query":"rust async tutorial","timeRange":"year"}

Why this works: LLMs are extraordinarily good at pattern-matching from examples. A single well-chosen example often beats two paragraphs of prose explanation. When to use:

Tools with enums or specific value formats (timezones, country codes, ISO dates)
Tools where the LLM tends to over- or under-specify (e.g. always omits an optional field that improves results)
New tools you don’t have months of usage data on yet

Tips:

3–5 examples is the sweet spot. More doesn’t help and increases prompt cost.
Show variety, not similarity. The model already understands that strings can vary; show it the kinds of variation that matter.
Don’t include obvious “bad” examples — the model can latch onto them.

3. `toModelOutput` — async result transformer

const fetchOrder = defineTool({
  name: "fetchOrder",
  description: "Get order details from the warehouse system.",
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => {
    // Real implementation returns the full order with 500 line items.
    return JSON.stringify(await db.orders.fetchFull(orderId));
  },
  toModelOutput: async (rawResult, ctx) => {
    const text = typeof rawResult === "string" ? rawResult : rawResult.content;
    const order = JSON.parse(text);
    // Shrink to just what the LLM cares about.
    return JSON.stringify({
      orderId: order.orderId,
      status: order.status,
      total: order.total,
      itemCount: order.items.length,
      firstThreeItems: order.items.slice(0, 3),
    });
  },
});

Execution order:

tool.execute  ──▶  rawResult
                      │
                      ▼
          toModelOutput (if set)        ──▶  transformed
                      │
                      ▼
        artifact auto-conversion          ──▶ pointer (if oversized)
                      │
                      ▼
              cache, event bus, LLM context

toModelOutput runs BEFORE the artifact auto-converter, so if your transform shrinks the output below the threshold, no pointer is created. Signature:

toModelOutput?: (
  result: string | ToolResult,
  ctx: RunContext,
) => Promise<string | ToolResult>;

ctx gives you access to userId, tenantId, sessionState, eventBus — useful for tenant-aware transforms (redact PII per tenant policy, etc.). When to use:

Compress / summarize / redact tool output without modifying the underlying tool
Convert verbose API responses to LLM-friendly shapes
Strip secrets that shouldn’t reach the model (API keys, internal IDs)
A/B test response formats without touching execute

toModelOutput vs Memory Pointers:

Scenario	Use
You know exactly what fields the LLM needs	`toModelOutput`
You want the LLM to opt-in to expanding the data later	Memory Pointers
Both	Stack them: `toModelOutput` summarizes, then `art:` wraps if still too big

Putting it together

const fetchOrder = defineTool({
  name: "fetchOrder",
  description: "Get order details from the warehouse system.",
  parameters: z.object({ orderId: z.string() }),
  strict: true,
  inputExamples: [{ orderId: "ord_abc123" }, { orderId: "ord_9f3-2025" }],
  toModelOutput: async (result) => {
    const data = JSON.parse(typeof result === "string" ? result : result.content);
    return JSON.stringify({ id: data.orderId, status: data.status, itemCount: data.items.length });
  },
  execute: async ({ orderId }) => JSON.stringify(await db.orders.fetchFull(orderId)),
});

All three flags compose cleanly: strict ensures valid input, examples teach the model what valid input looks like, toModelOutput keeps the response footprint small.

Getting Started

Agents

Memory

Skills

Handoff

Cost Tracking

Semantic Cache

Eval Framework

Compliance & Audit

Culture System

Webhooks

Capacity Planning

Observability

Voice Agents

Browser Agents

Models

Teams

Workflows

Storage

Knowledge & RAG

Toolkits

MCP (Model Context Protocol)

A2A (Agent-to-Agent)

Edge & IoT

Transport

Queue

Scheduling

Advanced Features

v2.0 Features

Tool Polish (Strict, Examples, toModelOutput)

Tool Polish

1. `strict: true` — guaranteed valid arguments

2. `inputExamples` — N-shot demonstrations

3. `toModelOutput` — async result transformer

Putting it together

See also

​Tool Polish

​1. strict: true — guaranteed valid arguments

​2. inputExamples — N-shot demonstrations

​3. toModelOutput — async result transformer

​Putting it together

​See also

Tool Polish

1. `strict: true` — guaranteed valid arguments

2. `inputExamples` — N-shot demonstrations

3. `toModelOutput` — async result transformer

Putting it together

See also