Tools

How tools are modeled, listed, gated, and invoked

A tool is a single callable operation provided by a service. The OpenAPI adapter, for example, generates one tool per operation in the source document.

Tool Shape

The canonical shape is ToolDefinition from @cyrnel/sdk:

interface ToolDefinition {
  id: string;
  name: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  adapterDomain: Record<string, unknown>;
}

On disk:

• (serviceId, id) is the composite primary key. Tool id must be a valid TypeScript identifier.
• name is human-friendly; id is what code addresses.
• enabled is per-tool, a service can be enabled with some of its tools disabled.

Endpoints

Method	Path	Notes
GET	/tools	List & filter
GET	/tools/:serviceId/:toolId	Single tool (with schemas)
GET	/tools/:serviceId/:toolId/docs	Markdown reference for the tool
POST	/tools/:serviceId/:toolId/enabled	{ enabled: boolean }

Filtering /tools

Query parameters (all optional):

• serviceId: Restrict to one service
• query: Case-insensitive substring match against name and description
• enabled: true / false
• limit: Positive integer

The list response includes a derived effectivelyEnabled flag: tool.enabled && service.enabled. Use it when deciding what to surface to clients.

Tool docs

GET /tools/:serviceId/:toolId/docs returns text/markdown generated by the active environment module’s generateToolDocs. The bundled typescript-ivm renders a usage page including:

• the tool description
• a typed parameter list derived from inputSchema
• the return shape derived from outputSchema
• a copy-pasteable cyrnel.services[...].tools[...].invoke(...) snippet

If the environment is the bundled one, the docs are stable. If you write a custom environment that exposes a different runtime surface (e.g. Python), its generateToolDocs should render an example in that runtime.

Invocation From Code

The environment bindings expose tools for direct invocation:

const result = await cyrnel.services.weather.tools.forecast.invoke({ city: "..." });
cyrnel.output({ result });

See EnvironmentBindings.

Invocation Gating

cyrnel.invoke rejects with a structured error when:

Condition	Status
Service does not exist	404
Tool does not exist on the service	404
Service is disabled	409
Tool is disabled	409

These checks happen before the adapter is called, so a disabled tool cannot incur an outbound request.