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;
  summary?: 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.
• summary (optional) is a short plain-text label shown in lists and tool docs; description is the long-form markdown.
• 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: Free-text query. Triggers a hybrid FTS5 + vector similarity search (if vector search is available). It uses Reciprocal Rank Fusion (RRF) to combine results from both sqlite-vec vector search and FTS5 full-text match.
• enabled: true / false
• cursor: Opaque pagination token from the previous page’s nextCursor
• limit: Positive integer, 1–100 (default 20, clamped above 100)

The list response is the paginated envelope { items, nextCursor, hasMore } (see Pagination for cursor rules and error codes) and includes a derived effectivelyEnabled flag (tool.enabled && service.enabled) as well as hybrid search relevance metadata if a query was provided.

Search Relevance Metadata

When a search query is passed, the response items include the following metadata fields:

• score: number (optional): The combined hybrid relevance score calculated via Reciprocal Rank Fusion (RRF). Higher scores mean greater relevance.
• matchType: "fts" | "vector" | "both" (optional): Indicates which search strategy matched the tool.
• ftsRank: number (optional): The 1-indexed rank position returned by the FTS5 full-text engine.
• vectorRank: number (optional): The 1-indexed rank position returned by the vector similarity search.

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 summary and 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.