[object Object]

The tools you give a Zia agent are its API to the world. Tool design — not prompt engineering — is where most agent projects make or break themselves.

One Tool, One Verb

A tool should do one verifiable thing. update_deal_and_send_email_and_create_task is a wrapper, not a tool. Split it:

update_deal(id, fields)
send_email_to_contact(contact_id, template, vars)
create_task(record_id, title, due_date, owner)

Composition is the agent’s job. Pre-composed tools are how you end up with agents that do too much in one step and fail in mysterious ways.

Name Tools Like Internal API Endpoints

Good tool names read like REST endpoints:

get_account_summary(account_id)
list_open_deals(account_id, limit)
get_recent_activities(record_id, since_days, limit)

Verbs in lowercase, snake_case, plural for collections, singular for items. Consistency matters because the model uses the names as semantic hints.

Constrain Inputs Aggressively

Use input schemas with required fields, value enums, and ranges. An agent given an unconstrained priority parameter will set “extremely high”; given an enum of low|medium|high, it picks correctly:

create_task(
  record_id: required string,
  title: required string,
  priority: enum("low","medium","high"),
  due_date: required ISO date
)

Write Stable Error Contracts

When a tool fails, return a structured error the agent can reason about:

{
  "ok": false,
  "code": "RECORD_NOT_FOUND",
  "message": "Account not found",
  "retryable": false
}

Pattern-match in the agent’s instructions: “If code = RATE_LIMITED, wait 30 seconds and retry once.” The model handles structured errors well — free-text errors send it down rabbit holes.

Read Tools Are Cheap; Write Tools Are Expensive

Give the agent generous read access. Restrict write access aggressively. Every write tool should require explicit instructions for when to use it. Default to read-only and add writes as the agent earns trust.

Tool Idempotency

Where possible, make write tools idempotent. set_deal_stage(id, "Negotiation") called twice should be a no-op. Agents will occasionally call the same tool twice; idempotent tools tolerate this.

Logging Per Tool Call

Log every tool invocation with arguments, response, and elapsed time. This is your debugging surface. Without it, you’re guessing why the agent did what it did.

Don’t Build a Tool If a Workflow Rule Will Do

If the action is “stamp a field when a stage changes,” that’s a Workflow Rule, not a tool. Tools are for things that need decision-making — actions that can’t be expressed as if-this-then-that.

What to Do This Week

  1. List the tools any planned agent will need.
  2. Reject any tool that bundles multiple verbs; split them.
  3. Add input schemas with enums and required fields.
  4. Standardize the error envelope across all tools.
[object Object]
Share