> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool reference
> Tools the Amps MCP servers expose. Documentation MCP: search and shell-style filesystem query. Execution MCP: per-operation API tools, coming soon.
Two MCP servers, two tool surfaces. The Documentation MCP exposes two read-only tools that ground the agent in the docs corpus. The Execution MCP exposes a per-operation tool surface that mirrors the Amps API.
## Documentation MCP tools
Both Documentation MCP tools are read-only. Both are stateless: each call resets the working directory to `/` and discards shell variables or aliases.
### `search_amps_ai_documentation`
Semantic search across every Amps docs page. Returns ranked snippets with titles, page paths, and direct links. Reach for it on conceptual queries where the right page is uncertain.
#### Input
```json theme={null}
{
"query": "string"
}
```
`query` is a natural-language question or keyword phrase. Required.
#### Output
A list of result entries. Each carries a `title`, a `link` to the public page, a `page` path, and a snippet of the matching content with the keyword highlighted.
```json theme={null}
[
{
"title": "Canonical Actions",
"link": "https://docs.amps.ai/concepts/canonical-actions",
"page": "concepts/canonical-actions",
"content": "Direct commands (charge, discharge, idle) are explicit instructions. Auto commands declare intent..."
},
{
"title": "Push battery action",
"link": "https://docs.amps.ai/api-reference/battery/push-battery-action",
"page": "api-reference/battery/push-battery-action",
"content": "Send a command to a battery device..."
}
]
```
For full content, follow up with `query_docs_filesystem_amps_ai_documentation` and `cat` or `head` the page path. Append `.mdx` when reading from the filesystem.
#### Example calls
| Query | Why |
| ---------------------------------- | --------------------------------------------------------------------------------- |
| `"how does scheduling work"` | Returns the scheduling concept page plus the cookbook overnight-charge recipe. |
| `"auto.balance behaviour"` | Returns the canonical-actions page and per-mode notes. |
| `"webhook signature verification"` | Returns the webhooks security page plus Node.js and Python verification snippets. |
| `"environments sandbox vs live"` | Returns the environments guide and the sandbox testing notes. |
### `query_docs_filesystem_amps_ai_documentation`
Read-only shell-style access to a virtual filesystem rooted at `/`. The filesystem holds every published documentation page as `.mdx` and the OpenAPI spec at `/openapi/openapi.json`. Reach for it on exact lookups: read a specific page, grep a canonical name, list endpoint paths.
#### Input
```json theme={null}
{
"command": "string"
}
```
`command` is a shell-flavoured command string. Required.
Supported commands: `rg` (ripgrep), `grep`, `find`, `tree`, `ls`, `cat`, `head`, `tail`, `stat`, `wc`, `sort`, `uniq`, `cut`, `sed`, `awk`, `jq`. No writes, no network, no process control. `--help` on any command for usage.
Each call is stateless. To run a sequence in one call, chain with `&&`:
```text theme={null}
ls /concepts && head -30 /concepts/canonical-actions.mdx
```
`cd` does not persist between calls. Use absolute paths.
#### Output
Plain text. Stdout, stderr, and the exit code, capped at 30KB per call. Beyond the cap, output truncates with a notice. Use targeted commands (`rg -C 3 'pattern' /path/file.mdx`, `head -200`) to stay under the limit.
#### Path-to-URL conversion
Filesystem paths end in `.mdx`. Public URLs do not. To cite a page in a response, strip the `.mdx`:
| Filesystem path | Public URL |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `/quickstart.mdx` | `https://docs.amps.ai/quickstart` |
| `/concepts/canonical-actions.mdx` | `https://docs.amps.ai/concepts/canonical-actions` |
| `/api-reference/battery/push-battery-action.mdx` | `https://docs.amps.ai/api-reference/battery/push-battery-action` |
#### Example calls
| Command | What it does |
| ------------------------------------------------------------------------------ | --------------------------------------------- |
| `tree / -L 2` | Show the top-level directory layout. |
| `ls /concepts` | List concept pages. |
| `cat /concepts/canonical-actions.mdx` | Read the full canonical-actions page. |
| `head -80 /get-started/quickstart.mdx` | Read the first 80 lines of the quickstart. |
| `rg -l "auto.balance" /` | List every page mentioning `auto.balance`. |
| `rg -C 3 "EXECUTION_NOT_SUPPORTED" /` | Show every match with three lines of context. |
| `cat /openapi/openapi.json \| jq '.paths \| keys'` | List every OpenAPI endpoint path. |
| `cat /openapi/openapi.json \| jq '.paths."/battery/{deviceId}".post.summary'` | Read a specific endpoint's summary. |
| `find /api-reference -name "*.mdx"` | Enumerate API reference pages. |
| `head -40 /guides/webhooks/verify-signatures.mdx /reference/webhook-types.mdx` | Read multiple pages in one call. |
#### Output cap and how to stay under it
The 30KB cap applies per call. A `cat` on the OpenAPI spec or a long concept page will truncate. Three patterns that stay safe:
1. `head -N path` when you only need the top of a file.
2. `rg -C N "pattern" path` when you need only the relevant slice.
3. `jq '.paths | keys'` and similar projections when the file is structured.
Combine with `&&` to keep round-trips down. Each call pays the connection cost on its own, so bundling pays off fast.
## Execution MCP tools
**Coming soon.** The Execution MCP is in development and will publish to [`@amps-ai/mcp`](https://www.npmjs.com/package/@amps-ai/mcp) on npm. Tool names and shapes below describe the planned surface; treat them as design intent until the package ships.
There is one tool per canonical API operation. The tool name follows the operation's verb-noun pattern, lowercased and snake-cased.
### Per-resource tools
| Tool | What it does |
| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `list_battery` | List batteries the authenticated user has registered. |
| `get_battery` | Fetch one battery's state and capability declaration. |
| `push_battery` | Push a [canonical action](/concepts/canonical-actions) to a battery. Destructive. |
| `list_ev_charger`, `get_ev_charger`, `push_ev_charger` | Same trio for EV chargers. |
| `list_hvac`, `get_hvac`, `push_hvac` | Same trio for HVAC. |
| `list_solar_inverter`, `get_solar_inverter` | Read-only inverter access. |
| `list_vehicle`, `get_vehicle` | Read-only vehicle access. |
| `get_action` | Fetch one action's lifecycle state. |
| `cancel_action` | Cancel a scheduled or in-flight action. Destructive. |
### Helper tools
Helpers wrap canonical primitives in shapes the model finds easier to reason about.
| Tool | What it does |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait_for_action` | Polls `get_action` until the action reaches a terminal state (`completed`, `failed`, or `cancelled`). The agent does not have to manage its own loop. |
| `find_device` | Lookup-by-alias. Saves a `list_*` then filter pass when the user names a device by its label rather than ID. |
### Filtered out
The 501 [`/schedules`](/concepts/scheduling) surface is filtered until it ships, so the agent never gets a tool that always fails.
## What next
Concrete workflows that combine the tools above.
Wire either MCP server into your AI tool.
The vocabulary the tools surface to the model.
Why `push_*` and `cancel_action` should not free-fire from the model.