Tools

Tools let an agent take controlled product actions during a turn — look up an order, create a ticket, schedule a callback, fetch the user’s plan, or call any HTTP endpoint you control.

Hyponema supports four buckets:

• Built-in (memory-managed) — auto-attached to every agent, hidden from the catalog.
• Built-in (operator opt-in) — attached but disabled by default; turn on per agent.
• System — always available, cannot be disabled.
• Custom — workspace-scoped tools you register. Two kinds: HTTP and MCP.

Built-in and system tool names are reserved — custom tools cannot reuse them.

Built-in tools

Bucket	Tools	Behavior
Memory-managed	search_memory, add_memory_note, record_persona_statement	Auto-attached to every agent. Hidden from the operator catalog.
Operator opt-in	schedule_callback, manage_callback	Ship disabled per agent. The operator turns them on. schedule_callback dials PSTN minutes. manage_callback lists, cancels, and reschedules existing entries — including operator-authored recurring schedules.
System	end_call, language_detection, skip_turn	Always available, cannot be disabled.

Custom tools — HTTP

A custom HTTP tool wraps an endpoint you host. The agent calls the model, the model decides to invoke the tool, Hyponema renders dynamic variables (if allowed), POSTs (or GETs / PATCHes) to your URL, and feeds the response back to the model.

Each HTTP tool defines:

• Slug — stable name the model sees.
• Description — model-facing description; this is how the model decides when to call the tool.
• Input schema — JSON Schema for the arguments. The model is constrained to this shape.
• Webhook URL — endpoint to call.
• Method — GET, POST, PATCH, PUT, or DELETE.
• Headers, query params, hardcoded query params, path params — the wire shape.
• Auth header — encrypted at rest with AES-256-GCM envelope encryption.
• allow_dynamic_vars — whether {{variable}} substitution runs against the call.

Register from the dashboard

Open Tools → New in the dashboard. Pick HTTP, fill the slug, description, input schema, URL, and any headers, then save. Attach the tool to an agent from the agent’s Tools tab.

Register from the API

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/tools" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "lookup_order",
    "description": "Look up an order by its public ID. Returns status, ETA, and contents.",
    "kind": "http",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string", "description": "Public order ID." }
      },
      "required": ["order_id"],
      "additionalProperties": false
    },
    "webhook_url": "https://api.example.com/orders/{order_id}",
    "method": "GET",
    "path_params": ["order_id"],
    "auth_header": "Bearer sk_live_..."
  }'

Attach the tool to an agent:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/tools/attach" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tool_id": "tool_...", "enabled": true }'

Detach with DELETE /workspaces/{ws}/agents/{agent_id}/tools/{tool_id}.

Test before going live

POST /workspaces/{ws}/tools/{tool_id}/run invokes the tool against your real endpoint with a stubbed agent context. Use this from the dashboard’s tool detail page or directly:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/tools/$TOOL_ID/run" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "args": { "order_id": "ORD-123" } }'

Custom tools — MCP

A custom MCP tool bridges to an external Model Context Protocol server. Hyponema acts as the MCP client. The model sees the MCP server’s tools through the same workspace tool catalog as HTTP tools.

Set kind: "mcp" and mcp_server_url instead of webhook_url:

{
  "slug": "ops_console",
  "description": "Operations console for internal lookups.",
  "kind": "mcp",
  "input_schema": { "type": "object", "properties": {} },
  "mcp_server_url": "https://mcp.example.com/sse",
  "auth_header": "Bearer mcp_..."
}

MCP tools are subject to the same plan entitlement check as HTTP tools, plus an MCP-enabled flag on the workspace plan. Dashboard and API both surface a clear error when MCP is not on the active plan.

The retired in-process MCP server (the one that exposed Hyponema memory through MCP) is gone. Memory access is built in; you do not need to register an MCP tool for it.

Runtime resolution

The agent’s tool registry is composed in this order, deduplicated by name:

1. Workspace-attached custom tools.
2. Bound built-in tools (memory-managed plus operator opt-in if enabled).
3. System tools.

Custom tools resolve before built-ins so a workspace tool with the same name will shadow a built-in. The reserved-name guard in tool creation prevents this from happening accidentally.

Dynamic variables in tool calls

Built-in and system tools never receive template substitution. Custom tools opt in by setting allow_dynamic_vars: true. When enabled, {{variable}} placeholders inside the URL, headers, query params, and JSON body are rendered against the session’s resolved variables before the call.

See the Dynamic variables guide for how variables are sourced and overridden per session.

Production checklist

• Test the tool endpoint with representative payloads through /run.
• Confirm authentication and timeout behavior — Hyponema retries idempotent failures.
• Run a real session that forces the tool call and inspect the trace for input, output, latency, and errors.
• Keep tool responses compact. Hand the model the data it needs to act, not the full payload.
• Use max_calls_per_session on the agent attachment to cap loops.

Disable a built-in tool per agent

PATCH /workspaces/{ws}/agents/{agent_id}/tools-config with disabled_tools: ["schedule_callback"] turns the named built-in off without unattaching it. System tools cannot be disabled.

Reading the catalog

GET /workspaces/{ws}/tools returns the merged catalog (built-ins + system + custom). Synthetic IDs are builtin:<name> / system:<name>; custom tools have UUID IDs.