Adam Tool Calling

Adam uses tools to move from conversation to action. Tools can query endpoints, run workflows, inspect metadata, call APIs, or perform operational tasks. Eve remains the access boundary for those actions.

Tool Calling Flow

Adam receives a user or agent request.
Adam resolves relevant endpoint and tool context.
Tool definitions are provided to the model.
The model selects a tool and proposes arguments.
Eve checks whether the subject can use the endpoint or action.
The tool executes through the governed path.
Adam returns the result to the conversation.
Telemetry records the attempt, result, latency, and error state.

Tool Design Principles

Good tools are narrow, auditable, and permission-aware.

Principle	Guidance
Narrow scope	One tool should do one clear operation.
Typed input	Use explicit arguments instead of free-form strings when possible.
Least privilege	A tool should require only the permissions its action needs.
Clear side effects	Mutating tools should declare what they change.
Approval points	High-impact tools should require human approval or a separate workflow gate.
Observable execution	Every call should record outcome, latency, subject, and endpoint context.

Read Tools And Write Tools

Separate read tools from write tools:

Read tools can inspect data, metadata, status, and telemetry.
Write tools can mutate data, change configuration, start workflows, approve migrations, or call external APIs.

Do not hide writes behind a tool name that sounds informational. A user or reviewer should be able to tell whether a tool can change production state.

Error Handling

Tool errors should preserve enough context to debug the action:

which tool ran,
which endpoint or workflow it targeted,
which subject requested it,
whether the error was permission, validation, backend, timeout, or policy related,
and whether a retry is safe.

Adam should not retry mutating tools blindly unless the tool is explicitly idempotent.

Operational Metrics

Monitor:

tool calls by tool and endpoint,
failure count and failure class,
p95 and p99 tool latency,
denied tool calls,
model requests that attempted unavailable tools,
approval wait time,
and token usage associated with tool-heavy conversations.