@equationalapplications/core-llm-tools

Zero-dependency Gemini function-calling schemas and capability-scoped tool injection for edge AI agents. Works in Node.js, browser, and React Native (Hermes).

📖 Docs · GitHub · ScopeLab · WikiDemo · Changelog · Issues

A universal registry bridging the gap between Edge AI (Expo/React Native) and Cloud Agents (Cloud Run).

Overview

core-llm-tools provides a shared, strictly-typed repository of JSON Function Declarations (Tools) for Gemini models. By decoupling the Tool Interface (the schema) from the Tool Implementation (the executing code), this package allows client-side triage agents and heavy backend cloud agents to share the exact same capabilities without importing Node.js server dependencies into the browser or mobile environments.

It also introduces a robust Capability-Based Scope Model (similar to OAuth 2.0), ensuring that Large Language Models are only injected with tools the user has explicitly authorized.

Features

• Platform-Agnostic — Zero runtime dependencies. Pure TypeScript. Compiles safely for Node.js, the browser, and the React Native Hermes engine.
• Capability-Based Security — Tools are locked behind specific scopes (e.g., calendar:read, messages:send). The injector ensures models cannot hallucinate calls to unauthorized tools.
• Strict Typings — Provides rigid interfaces (AgentToolSchema, AgentToolManifest) to prevent malformed Gemini API requests.
• Harmonized Edge/Cloud Routing — Enables lightweight edge models (like Gemini Nano) to triage intents using the exact same schemas the heavy Cloud Run backend uses to execute them.
• GraphRAG tool schemas — graphTraverseManifest and ontologyGetManifest are pre-built Gemini tool schemas for the GraphRAG retrieval API; see GraphRAG guide.

Installation

npm install @equationalapplications/core-llm-tools
# or
pnpm add @equationalapplications/core-llm-tools

Quick Start

1. Defining a Tool Manifest

Tools are defined by wrapping a standard Gemini JSON schema with a required security scope.

import type { AgentToolManifest } from '@equationalapplications/core-llm-tools';

export const getCalendarEventsManifest: AgentToolManifest = {
  name: 'get_calendar_events',
  scope: 'calendar:read', // Security scope required to use this tool
  schema: {
    name: 'get_calendar_events',
    description: 'Fetch the user\'s schedule for a given date.',
    parameters: {
      type: 'object',
      properties: {
        date: { type: 'string' }
      }
    }
  }
};

2. Injecting Authorized Tools

At runtime, use buildAuthorizedToolsArray to filter your tool library against the user's granted permissions. It returns the full Gemini tools[] array: at most one functionDeclarations group containing every authorized function tool's schema, plus one entry per authorized built-in tool (e.g. Google Search grounding).

import { buildAuthorizedToolsArray, escalateToCloudManifest } from '@equationalapplications/core-llm-tools';

// 1. Gather all manifests known to your app
const allAppTools = [escalateToCloudManifest, getCalendarEventsManifest];

// 2. Fetch the user's authorized scopes from your DB (e.g., SQLite/Postgres)
const userGrantedScopes = ['calendar:read'];

// 3. The injector automatically includes 'core' tools and authorized scoped tools,
//    collapsing all authorized function tools into a single functionDeclarations group
const tools = buildAuthorizedToolsArray(allAppTools, userGrantedScopes);
// => [{ functionDeclarations: [get_calendar_events, escalate_to_cloud] }]

// 4. Pass safely to Gemini
const response = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: userInput,
  config: { tools }, // @google/genai reads tools only from config
});

3. Built-In Tools (Grounding)

"Grounding" here means Gemini's server-side Google Search tool. It is unrelated to core-llm-wiki's evidence grounding check (WikiConfig.grounding), which verifies that facts quote their source.

Some Gemini capabilities, like Google Search grounding, are built-in tools executed server-side by Google rather than function declarations your code implements. These are declared with kind: 'built_in' and flow through the same capability-scope model as function tools, via buildAuthorizedToolsArray. Use AnyAgentToolManifest when mixing function and built-in manifests; AgentToolManifest remains the function-only type for existing callers:

import type { AnyAgentToolManifest } from '@equationalapplications/core-llm-tools';
import { buildAuthorizedToolsArray, googleSearchManifest, escalateToCloudManifest } from '@equationalapplications/core-llm-tools';

const allAppTools: AnyAgentToolManifest[] = [escalateToCloudManifest, googleSearchManifest];
const userGrantedScopes: string[] = [];

// Returns the full Gemini tools[] array: a functionDeclarations group (if any
// function tools are authorized) plus one entry per authorized built-in tool.
const tools = buildAuthorizedToolsArray(allAppTools, userGrantedScopes);
// => [{ functionDeclarations: [...] }, { googleSearch: {} }]
// The manifest is named `google_search`; the wire key is `googleSearch`,
// the only spelling @google/genai reads. The REST API accepts it too.
// The GeminiToolEntry type accepts both spellings, so call sites written
// against the pre-rename `google_search` shape keep compiling.

const response = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: userInput,
  config: { tools }, // @google/genai reads tools only from config
});

Note: When the model uses google_search, Gemini returns a groundingMetadata object (search queries, source citations, etc.) on the response. Parsing that metadata is the caller's responsibility — this package only handles the request-side tool declaration.

Memory manifests

ontology_get (ontologyGetManifest), graph_traverse (graphTraverseManifest), and instructions_get (instructionsGetManifest) are schema-only memory:read tools. Dispatch them to WikiMemory.getOntologyManifest, traverseGraph, and getInstructions. instructions_get returns your WikiConfig.prompts overrides verbatim, so keep secrets out of them. The names follow SynapseTree's <resource>_<verb> convention, which the @equationalapplications/mcp-server tools also use.

Removed in 8.0.0: the wiki_* tool names

LEGACY_TOOL_NAMES and canonicalToolName are removed too. Declare the new manifests and dispatch on the new names. A stored prompt that still tells a model to call an old name has to be updated, because the model no longer has a tool by that name.

Helpful Resources & Links

• Google Gen AI: Function Calling Tutorial — Official docs on how the JSON schemas in this package interact with Gemini models.
• JSON Schema Specification — Structural foundation for AgentToolSchema.parameters.
• OAuth 2.0 Scope Concepts — Inspiration behind the capability-based AgentScope permission hierarchy.
• @google/adk (Agent Development Kit) — Server-side framework used by Cloud Run backends to wrap and execute the schemas defined in this package.

Monorepo Ecosystem

Made with ❤️ by Equational Applications LLC. https://equationalapplications.com/