Shape tool inputs and results

Use defineTool to declare arguments, demonstrate useful calls, and reduce the result sent back to the model. The host still owns authorization and the underlying operation.

Request a strict tool schema

This standalone definition uses local fixture data. Add the returned tool to an Agent’s tools array to let the model call it.

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

export const lookupOrder = defineTool({
  name: "lookupOrder",
  description: "Look up the demonstration order.",
  parameters: z.object({ orderId: z.string() }),
  strict: true,
  execute: async ({ orderId }) => JSON.stringify(
    orderId === "order-42" ? { orderId, status: "shipped" } : { error: "Unknown order" },
  ),
});

The tool serializer includes the strict flag and sets additionalProperties: false on its schema. Provider support and accepted JSON Schema features differ; do not treat this flag as a guarantee that every provider will generate valid arguments. Agentium validates tool arguments before execution. Business rules and record access still belong in the tool or execution policy.

Show useful argument combinations

inputExamples appends serialized examples to the model-visible tool description. Use examples that distinguish meaningful options. They are prompt content, not additional validation rules. This factory takes an application-owned search function. It performs no search until the Agent calls the tool.

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

const searchInput = z.object({ query: z.string(), timeRange: z.enum(["day", "week", "all"]).optional() });
type SearchInput = z.infer<typeof searchInput>;

export function createSearchTool(search: (input: SearchInput) => Promise<string>) {
  return defineTool({
    name: "search", description: "Search the application's approved sources.",
    parameters: searchInput,
    inputExamples: [
      { query: "shipping policy" },
      { query: "release changes", timeRange: "week" },
    ],
    execute: search,
  });
}

Verify that the model chooses the intended range on representative requests. More examples also consume prompt space; keep only those that improve the task.

Reduce the model-visible result

toModelOutput runs after execute and before the tool result is added to model context. Keep the complete business record in its authoritative store and return only the fields needed for this answer.

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

const orderSchema = z.object({
  orderId: z.string(), status: z.string(),
  items: z.array(z.object({ name: z.string(), quantity: z.number() })),
});
type Order = z.infer<typeof orderSchema>;

export function createOrderTool(fetchAuthorizedOrder: (orderId: string) => Promise<Order>) {
  return defineTool({
    name: "fetchOrder", description: "Read an order the caller is authorized to access.",
    parameters: z.object({ orderId: z.string() }),
    strict: true,
    inputExamples: [{ orderId: "order-42" }],
    execute: async ({ orderId }) => JSON.stringify(await fetchAuthorizedOrder(orderId)),
    toModelOutput: async (result) => {
      const order = orderSchema.parse(JSON.parse(typeof result === "string" ? result : result.content));
      return JSON.stringify({ orderId: order.orderId, status: order.status, itemCount: order.items.length });
    },
  });
}

For an order with 500 items, the model receives the order ID, status, and count instead of all item details. The host callback must authorize access using its verified request context. A transform cannot retroactively prevent unauthorized data access or remove data already logged by your service.

Combine and verify

The order factory combines all three controls. Check an unknown ID, an unauthorized record, malformed service data, and a successful record. Observe the actual tool outcome and model-visible summary. Use the quality-gate recipe to turn important behavior into assertions. Use memory pointers when the model needs to retrieve a larger artifact later. See tool-loop detection for repeated calls and the tool API for exact types.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Shape tool inputs and results

Request a strict tool schema

Show useful argument combinations

Reduce the model-visible result

Combine and verify

​Request a strict tool schema

​Show useful argument combinations

​Reduce the model-visible result

​Combine and verify

Request a strict tool schema

Show useful argument combinations

Reduce the model-visible result

Combine and verify