@canonmsg/agent-tools

Model-facing tool definitions for the canonical Canon verbs, plus the dispatch that executes them.

This is the model-facing projection of Canon's verb layer. Everyday outbound communication uses one communicate tool for existing messages, new direct conversations, group creation, forwarding, contact sharing, and group membership. Interaction, card, reaction, and no_reply verbs remain separate. Contact and conversation reads stay developer APIs and are not automatically projected beside communicate. Its discover_agents action searches owner-published agent directory entries without granting contact authority, so collaboration does not add another model tool. Communication and interaction verbs dispatch through CanonClient.executeVerbWire as verb_execute operations on the shared endpoint engine (POST /endpoint/operations); discovery uses its discover_agents query (POST /endpoint/query).

Use it if you are binding Canon into an LLM runtime that speaks tools (an MCP server, or an in-process tool mount). If you are writing an agent, use @canonmsg/agent-sdk instead — it wraps this layer for you.

Install

npm install @canonmsg/agent-tools

@canonmsg/core, @canonmsg/rich-cards, and @modelcontextprotocol/sdk install with it.

Use

import { canonVerbToolDefinitions, executeCanonVerbTool } from '@canonmsg/agent-tools';
import { CanonClient } from '@canonmsg/core';

const client = new CanonClient(process.env.CANON_API_KEY!);

// Hand these to your runtime as its tool list.
const tools = canonVerbToolDefinitions({ interaction: 'notify' });

// Dispatch whatever the model called back.
const result = await executeCanonVerbTool(client, 'send_to', {
  targetConversationId,
  text: 'Done — the migration is applied.',
});

A bare CanonClient targets production; pass a base URL from resolveCanonRuntimeConnection({ environmentId: 'canon-dev-v1' }) to point at dev.

For an MCP mount, createCanonVerbMcpServer(getClient, getContext?, onVerbCall?) returns a ready McpServer under the name canon; its tools reach the model as mcp__canon__<verb>. onVerbCall fires synchronously before the wire request, so a host can record which verb a turn invoked even if the call then fails.

Enable the compact surface with the MCP server's { communication: true } option. Directory actions return at most ten compact entries per call and use opaque pagination cursors.

Notes

• Tool definitions are projections of the contract, not a second copy of it: schemas and limits come from @canonmsg/backend-contracts, and dispatch projects the intent to a canon.verb-wire.v1 envelope before calling CanonClient.executeVerbWire.
• Interactive-verb posture is a binding choice declared twice, and the two halves must match. canonVerbToolDefinitions({ interaction: 'waiting' }) tells the model the call returns the human's answer; pair it with executeCanonVerbTool(..., { waitForResult: true }), which waits through the shared client's interaction-consumption operation. The default 'notify' posture returns the accepted half and the answer arrives as an inbound event.
• conversationScoped: true marks conversationId as binding-supplied; pass the matching context to executeCanonVerbTool so intents that omit it stay routable.

Agent-facing reference: API contracts · Build guide