Skip to content

Commit 2d8d1a7

Browse files
dsp-antdsp-ant
committed
Add tools API specification
Defines the tools API for the Model Context Protocol, enabling servers to expose functions that can be invoked by language models through clients. Includes capabilities, message formats, error handling, and security considerations. The spec covers tool listing, invocation, and change notifications.
1 parent 335bb87 commit 2d8d1a7

File tree

1 file changed

+305
-0
lines changed

1 file changed

+305
-0
lines changed

‎docs/spec/tools.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
---
2+
title: Tools
3+
type: docs
4+
weight: 5
5+
---
6+
Tool use enables servers to expose tools (also sometimes called functions) that can be invoked by language models through the client. This allows models to perform actions or retrieve information beyond their training data. Clients can discover available tools, retrieve their specifications, and invoke them on behalf of the model. Each tool is uniquely identified by a name.
7+
8+
## Capabilities
9+
10+
To indicate support for the Tools API, servers MUST include a `tools` capability in their `ServerCapabilities` during initialization. The `tools` capability MAY be an empty object:
11+
12+
```json
13+
{
14+
"capabilities": {
15+
"tools": {}
16+
}
17+
}
18+
```
19+
20+
Clients SHOULD check for this capability before attempting to use any Tools API methods. If the capability is not present, clients SHOULD assume that the server does not support tool functionality.
21+
22+
Servers MAY support notifications for changes to the tool list. If a server supports this feature, it SHOULD include a `listChanged` property in its `tools` capability:
23+
24+
```json
25+
{
26+
"capabilities": {
27+
"tools": {
28+
"listChanged": true
29+
}
30+
}
31+
}
32+
```
33+
34+
If a server supports this capability, it MAY send [`notifications/tools/list_changed`](#tool-list-changed-notification) notifications to inform the client about changes to the available tools.
35+
## Concepts
36+
37+
### Tool
38+
39+
A Tool in the Model Context Protocol (MCP) represents a function or action that can be invoked by a language model through the client. Each Tool is uniquely identified by a name and has associated metadata such as a description and input schema. Tools can represent various types of actions, including data retrieval, calculations, or external API calls.
40+
41+
### Tool Specifications
42+
43+
Tool Specifications describe the structure and expected inputs for each tool. They use JSON Schema to define the input parameters, allowing clients and models to understand how to properly invoke the tools.
44+
45+
## Use Cases
46+
47+
Common use cases for tools include data retrieval, performing calculations, or interacting with external services. Here are examples of kinds of tools that an MCP server could expose:
48+
49+
### Weather Information
50+
51+
A tool for retrieving current weather information:
52+
53+
```json
54+
{
55+
"name": "get_weather",
56+
"description": "Get current weather information for a specific location",
57+
"inputSchema": {
58+
"type": "object",
59+
"properties": {
60+
"location": {
61+
"type": "string",
62+
"description": "City name or zip code"
63+
},
64+
"units": {
65+
"type": "string",
66+
"enum": ["metric", "imperial"],
67+
"default": "metric"
68+
}
69+
},
70+
"required": ["location"]
71+
}
72+
}
73+
```
74+
75+
### Database Query
76+
77+
A tool for querying a database:
78+
79+
```json
80+
{
81+
"name": "query_database",
82+
"description": "Execute a SQL query on the database",
83+
"inputSchema": {
84+
"type": "object",
85+
"properties": {
86+
"query": {
87+
"type": "string",
88+
"description": "SQL query to execute"
89+
},
90+
"database": {
91+
"type": "string",
92+
"enum": ["users", "products", "orders"],
93+
"default": "users"
94+
}
95+
},
96+
"required": ["query"]
97+
}
98+
}
99+
```
100+
101+
## Diagram
102+
103+
The following diagram visualizes a common interaction sequence between
104+
client, server, and language model for using tools:
105+
106+
```mermaid
107+
sequenceDiagram
108+
participant Model
109+
participant Client
110+
participant Server
111+
112+
Note over Client,Server: List tools
113+
Client->>Server: tools/list
114+
Server-->>Client: ListToolsResult
115+
Client->>Model: Available tools
116+
117+
Note over Model,Client: Model selects tool
118+
Model->>Client: Use get_weather tool
119+
Client->>Server: tools/call (get_weather)
120+
Server-->>Client: CallToolResult
121+
Client->>Model: Tool result
122+
123+
Note over Model,Client: Model processes result
124+
Model->>Client: Generated response
125+
```
126+
127+
## Messages
128+
129+
This section defines the protocol messages for tool management in the Model Context Protocol (MCP).
130+
131+
### Listing Tools
132+
The Listing Tools operation allows clients to discover available tools on the server. When a client sends a `tools/list` request, the server responds with a comprehensive list of tools it can provide. This list enables clients to understand what tools are available, facilitating subsequent operations such as tool invocation.
133+
134+
> **_NOTE:_** Tools can change over time. In such cases, the server may send a [Tool List Changed Notification](#tool-list-changed-notification) to inform the client about updates to the available tools.
135+
136+
#### Request
137+
138+
To retrieve a list of available tools from the server, the client MUST send a `tools/list` request.
139+
140+
* Method: `tools/list`
141+
* Params: None
142+
143+
Example request from a client to a server:
144+
```json
145+
{
146+
"jsonrpc": "2.0",
147+
"id": 1,
148+
"method": "tools/list"
149+
}
150+
```
151+
152+
#### Response
153+
154+
The server MUST respond with a `ListToolsResult` containing:
155+
156+
- `tools`: An array of `Tool` objects
157+
158+
Example:
159+
```json
160+
{
161+
"jsonrpc": "2.0",
162+
"id": 1,
163+
"result": {
164+
"tools": [
165+
{
166+
"name": "get_weather",
167+
"description": "Get current weather information for a specific location",
168+
"inputSchema": {
169+
"type": "object",
170+
"properties": {
171+
"location": {
172+
"type": "string",
173+
"description": "City name or zip code"
174+
},
175+
"units": {
176+
"type": "string",
177+
"enum": ["metric", "imperial"],
178+
"default": "metric"
179+
}
180+
},
181+
"required": ["location"]
182+
}
183+
},
184+
{
185+
"name": "query_database",
186+
"description": "Execute a SQL query on the database",
187+
"inputSchema": {
188+
"type": "object",
189+
"properties": {
190+
"query": {
191+
"type": "string",
192+
"description": "SQL query to execute"
193+
},
194+
"database": {
195+
"type": "string",
196+
"enum": ["users", "products", "orders"],
197+
"default": "users"
198+
}
199+
},
200+
"required": ["query"]
201+
}
202+
}
203+
]
204+
}
205+
}
206+
```
207+
208+
### Calling a Tool
209+
210+
#### Request
211+
212+
To invoke a specific tool, the client MUST send a `tools/call` request.
213+
214+
Method: `tools/call`
215+
Params:
216+
- `name`: The name of the tool to call (string, required)
217+
- `arguments`: An object containing the tool's input parameters (object, optional)
218+
219+
Example:
220+
```json
221+
{
222+
"jsonrpc": "2.0",
223+
"id": 2,
224+
"method": "tools/call",
225+
"params": {
226+
"name": "get_weather",
227+
"arguments": {
228+
"location": "New York",
229+
"units": "imperial"
230+
}
231+
}
232+
}
233+
```
234+
235+
#### Response
236+
237+
The server MUST respond with a `CallToolResult` containing:
238+
239+
- `toolResult`: The result of the tool invocation (any JSON-serializable value)
240+
241+
Example:
242+
```json
243+
{
244+
"jsonrpc": "2.0",
245+
"id": 2,
246+
"result": {
247+
"toolResult": {
248+
"temperature": 72,
249+
"humidity": 65,
250+
"description": "Partly cloudy"
251+
}
252+
}
253+
}
254+
```
255+
256+
### Tool List Changed Notification
257+
258+
If the server supports the `listChanged` capability for tools, it MAY send a `notifications/tools/list_changed` notification to inform the client that the list of available tools has changed.
259+
260+
#### Notification
261+
262+
Method: `notifications/tools/list_changed`
263+
Params: None
264+
265+
Example:
266+
```json
267+
{
268+
"jsonrpc": "2.0",
269+
"method": "notifications/tools/list_changed"
270+
}
271+
```
272+
273+
Upon receiving this notification, clients SHOULD request an updated tool list using the `tools/list` method to ensure they have the most up-to-date information about available tools.
274+
275+
## Error Handling
276+
277+
Clients MUST be prepared to handle cases where listed tools become unavailable between listing and invocation attempts. Servers SHOULD provide appropriate error responses in such scenarios.
278+
279+
Servers MUST return error responses when:
280+
- An unknown tool is requested
281+
- Invalid arguments are provided
282+
- The tool execution fails
283+
284+
Example error response:
285+
```json
286+
{
287+
"jsonrpc": "2.0",
288+
"id": 3,
289+
"error": {
290+
"code": -32602,
291+
"message": "Invalid params",
292+
"data": {
293+
"reason": "Missing required argument: location"
294+
}
295+
}
296+
}
297+
```
298+
299+
## Security Considerations
300+
301+
Implementations MUST carefully consider the security implications of exposing tools, especially when dealing with sensitive data or external services. Proper authentication and authorization mechanisms SHOULD be in place to prevent unauthorized access to tools.
302+
303+
Clients SHOULD implement user permission prompts before executing tools, especially for tools that may have side effects or access sensitive information. This allows users to maintain control over the actions performed by the language model.
304+
305+
Servers SHOULD implement rate limiting and input validation to prevent abuse of tool invocations.

0 commit comments

Comments
 (0)