Tools and effects

A Noir tool is a typed async function plus the metadata required to run it safely inside a durable loop.

import { jsonSchema, tool } from '@noir-agent/agent'

const lookupCustomer = tool({
  description: 'Find one customer by email.',
  input: jsonSchema<{ email: string }>({
    type: 'object',
    properties: { email: { type: 'string' } },
    required: ['email'],
    additionalProperties: false,
  }),
  effect: 'read',
  retry: 'safe',
  async execute({ email }) {
    return billing.lookupCustomer(email)
  },
})

The contract

input.parse is the trust boundary for model arguments. output can validate provider output. project converts the trusted internal result into the smaller shape the model should see. maxOutputBytes adds a tool-specific cap.

Do not expose raw database rows, storage pointers, secrets, or confusing internal discriminators to a model. Project a clean result at the tool boundary.

Effect metadata

effect describes what the call can do:

• read: inspect state without mutation.
• write: create or change state.
• destructive: delete or irreversibly alter state.
• external-message: communicate with another person or external audience.

approval is never, requester, or always. retry is safe, idempotent, or never. These fields are independent: a read can still be sensitive, and an approved write can still be unsafe to replay.

Provider-native tools

noir() accepts current AI SDK tools and converts their schemas and execute functions. Provider-executed tools are rejected because Noir cannot enforce local policy, checkpoints, or approval around an effect it never executes.

Namespacing

Top-level tool groups become group.tool. Connector tools become connectorName.tool. Plugin tools are namespaced by the plugin name. Tool groups may not be nested more than one level.

tools: {
  analytics: { query, explain },
  now,
}

Prefer a connector when tools share an external client. Prefer a plugin when the bundle also needs policy, prompts, hooks, routes, services, or lifecycle.