Tools

How to define API actions within a plugin — HTTP method, path, input/output schemas, and headers.

What is a Tool?

A tool is a single API action within a plugin. There are two types:

Manual tools — mapped to one HTTP endpoint on the external service. You define the method, path, and schemas. The runtime proxy uses these to build and execute HTTP requests.
MCP tools — auto-discovered from the plugin's MCP server. Read-only, managed automatically via the MCP protocol.

When an AI agent calls session.execute("TOOL_SLUG", params), NIN routes the call to either the REST proxy (manual) or the MCP server (MCP) based on the tool's source.

Tool Fields

Field	Type	Required	Description
`slug`	string	Yes	Unique within the plugin, uppercase with underscores (e.g. `GMAIL_SEND_EMAIL`)
`name`	string	Yes	Human-readable name (e.g. "Send Email")
`description`	string	Yes	What the tool does — shown to agents for tool selection
`method`	string	Yes	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
`path`	string	Yes	URL path appended to the plugin's base URL (e.g. `/v1/messages/send`)
`inputSchema`	JSON	No	JSON Schema describing the expected parameters
`outputSchema`	JSON	No	JSON Schema describing the response shape
`headers`	JSON	No	Static headers merged into every request for this tool
`enabled`	boolean	No	Whether the tool is available (default: `true`)

Path Parameters

Paths can contain {placeholder} segments that are interpolated from the params at execution time. For example:

Path: /v1/users/{userId}/messages
Params: { userId: "abc123", text: "hello" }
Result: GET /v1/users/abc123/messages with { text: "hello" } as body

Any param that matches a {placeholder} in the path is used for interpolation. Remaining params become the request body (for non-GET methods).

Creating a Tool

Open a plugin's detail page
Go to the Tools tab
Click Add Tool
Fill in slug, name, description, method, and path
Optionally provide input/output JSON schemas and static headers
Save

Execution Flow

When a tool is executed via POST /api/v1/tools/execute:

The tool is resolved by slug
Plugin's base URL is fetched
End-user's connected account is found
Credentials are decrypted and auth is injected into headers
Path params are interpolated, remaining params become the body
HTTP request is sent to {baseUrl}{path}
Response is returned with status and latency
Execution is logged to execution_logs

MCP Tools

For plugins with toolSource set to "mcp" or "both", tools are auto-discovered from the MCP server.

MCP Tool Cache (`mcpToolCache`)

Discovered MCP tools are stored in the mcp_tool_cache table:

Field	Type	Description
`id`	uuid	Primary key
`pluginId`	uuid	References the plugin
`mcpToolName`	string	Original name from the MCP server (e.g. `notion-search`)
`slug`	string	Normalized slug (e.g. `NOTION_SEARCH`)
`name`	string	Display name
`description`	string	Tool description from the MCP server
`inputSchema`	jsonb	JSON Schema for tool parameters
`lastSyncedAt`	timestamp	When this tool was last synced

A unique constraint on (pluginId, mcpToolName) ensures no duplicate tools per plugin.

Syncing MCP Tools

MCP tools can be synced in two ways:

Realtime — when getTools() is called with a userId, NIN connects to the MCP server live and fetches current tools. The cache is updated as a side effect.
Manual sync — click Sync Tools on the plugin detail page or Sync to Plugin Toolkit on a connection card. This triggers a sync using the admin's or user's MCP token.

MCP Tools in the Dashboard

MCP tools appear as read-only cards in the plugin's Tools tab. They show:

Tool name and description (expandable)
Input schema (viewable via Schema button)
lastSyncedAt timestamp
An MCP badge to distinguish from manual tools

MCP tools cannot be edited or deleted manually — they are managed by the MCP server.

API Endpoints

Manual Tools

Method	Path	Description
`POST`	`/api/dashboard/plugins/[pluginId]/tools`	Create a manual tool
`PUT`	`/api/dashboard/plugins/[pluginId]/tools`	Update a manual tool (by `id` in body)
`DELETE`	`/api/dashboard/plugins/[pluginId]/tools?id=...`	Delete a manual tool

MCP Tools

Method	Path	Description
`POST`	`/api/dashboard/plugins/[pluginId]/mcp-sync`	Sync MCP tools from the server to cache
`GET`	`/api/dashboard/connections/[connectionId]/tools`	Fetch tools for a specific connection (live for MCP)

All tool endpoints require admin authentication.

Tools

On this page