This is an MCP server that gives AI agents a shared, cooperative view and control over GPU VRAM, primarily for Ollama models.
Inspect GPU memory status, loaded models, process/activity details, and pressure state (ok/tight/degraded/thrashing) via vram_status and list_loaded.
View active model claims and capacity reservations with list_claims.
Declare model usage with claim, reserve VRAM for non-Ollama work with reserve, and extend or end them with renew/release.
Free up memory by unloading specific models (unload) or reaching a free-space target (ensure_free), respecting claims and busy protection unless forced.
Load or refresh Ollama model residency with warm, including keep-alive durations.
Investigate changes with history (audit trail) and trend (free-VRAM over time).
Get configuration suggestions via advise.
Coordinate safely across sessions under the same OS user: claims, reservations, pending operations, and audit logging prevent accidental evictions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vram-mcp Free up 2GB of VRAM"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI agents a shared view of GPU memory. Through MCP, they can inspect what's using VRAM, make room for Ollama models, and see which sessions are already relying on them.
Each client runs its own server; sessions under the same OS user share claims, reservations, pending-operation records, and an audit log. Capacity and process readings apply to one configured GPU. Claimed or recently busy models are protected from eviction by default.
Use Python 3.10+, a running Ollama instance, and an NVIDIA GPU with
drivers for memory readings. Windows and Linux are tested. Without
nvidia-smi or NVML, model operations and claims still work, but some readings
are unavailable.
Run vram-mcp on the machine hosting Ollama and the GPU. Changing
OLLAMA_BASE_URL redirects model requests; GPU and process inspection always
remain local. On a multi-GPU host, set VRAM_MCP_GPU_INDEX in every client's
server environment to select the same device; the default is GPU index 0.
With uv and Git
installed, choose your client below. uvx fetches vram-mcp from GitHub into an
isolated environment; no source checkout is needed.
claude mcp add vram --scope user -- uvx --from git+https://github.com/sushiHex/vram-mcp vram-mcpcodex mcp add vram -- uvx --from git+https://github.com/sushiHex/vram-mcp vram-mcpHermes — merge into ~/.hermes/config.yaml:
mcp_servers:
vram:
command: uvx
args: ["--from", "git+https://github.com/sushiHex/vram-mcp", "vram-mcp"]Merge this entry into your client's MCP configuration:
{
"mcpServers": {
"vram": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sushiHex/vram-mcp", "vram-mcp"]
}
}
}If the client cannot find uvx, use its absolute executable path. In JSON,
Windows paths need escaped backslashes, such as C:\\tools\\uvx.exe.
Reconnect your client after registration. It launches the server over stdio;
running vram-mcp by hand waits for MCP input. Prefer a local installation?
See installing from source.
Ask your agent:
Check GPU memory with vram-mcp. Show what's loaded, who is using it, and how much room is left. Report any unavailable readings.
The agent should call vram_status() and list_claims(). Status includes a
readable summary, the selected GPU, loaded models, available process details,
and observations metadata. Check each observation's status; unavailable
means the corresponding value is unknown, rather than empty or zero.
list_claims() also shows capacity reserved for training or other non-Ollama
work.
Related MCP server: Ollama MCP Server
These examples are MCP tool calls made inside a connected client, not shell
commands or a Python API. Use a descriptive session label for owner and by,
such as codex:review, so another agent can identify your work.
Inspect before changing memory. Call vram_status() and list_claims().
Model names are canonicalized consistently: a bare final name such as
llama3 becomes llama3:latest; comparison is case-insensitive, and
Ollama's default registry/library prefix is removed.
Claim a model before relying on it. Replace the example model below
with one already installed in Ollama. Continue only if the claim succeeds,
and save its returned claim_id.
claim(model="llama3:latest", owner="codex:review", purpose="Review local code")Make room when needed. ensure_free(gb=8, by="codex:review") unloads
unprotected models largest-first. Choose the target for your workload and
check outcome, free_mb, declined, reserved_mb, and observations.
It does not evict when selected-GPU capacity or Ollama residency is unknown.
Reaching the target does not give you ownership of that space.
Load and check. Call
warm(model="llama3:latest", keep_alive="10m", by="codex:review") when needed.
Inspect outcome, reason, and observations. succeeded means residency
was reconciled after the request; refused means no Ollama request was sent;
failed means Ollama definitively rejected it; and unknown means the
request may still be running and includes pending_until. Do not retry a
same-model mutation until that pending window ends. Warm admission is also
serialized across models sharing the selected GPU. A model that was already
resident has zero incremental residency cost (reason="already_resident").
Loading successfully does not guarantee full GPU residency. Run inference
through your usual Ollama client.
Renew and release. Claims expire after one hour by default. Call
renew(claim_id="<returned claim_id>") before expiry for longer work and
release(claim_id="<returned claim_id>") when finished, including if loading
fails. Releasing a claim does not unload the model; claim expiry and Ollama's
keep_alive are separate.
For training or diffusion, use reserve(gb=8, owner="codex:training", purpose="LoRA training") to declare capacity, then renew/release its claim_id
in the same way. A reservation records intent; it does not allocate memory.
Validation rejects invalid requests: capacities, TTLs, and trend windows
must be finite and positive; model, owner, purpose, and caller labels must be
nonblank; warm accepts a positive Ollama duration or -1 for indefinite
residency. Use unload() rather than a zero keep_alive.
Coordination is cooperative. Direct Ollama calls can bypass it. force=True
on unload, ensure_free, or warm overrides claims, busy protection, or
reservation admission; use it only after resolving competing work. It does not
bypass an unreadable coordination ledger or another pending mutation.
busy=null means unknown and does not block eviction on its own. See
coordination details.
| Meaning |
| Nothing is wrong, and every input that claim rests on was actually read. Missing evidence yields |
| Less than 1 GiB is free on the selected GPU. |
| Ollama placed part of a model on the CPU; expect slower inference. |
| Unexplained non-local memory meets the spill threshold and, when free VRAM is known, exceeds it. Driver paging is suspected. |
Missing required telemetry produces pressure.state="unknown". Read
pressure.coverage and top-level observations to see which evidence was
available. Driver-spill detection is best effort and requires non-local memory
that can be attributed to the selected GPU; adapter-aggregated Windows counters
do not establish that. CPU offload is tracked separately. Disabling auditing
stops history detection and trend sampling, but does not disable current GPU or
process observations.
Use history() to investigate a model disappearing and trend(hours=1) to
review memory changes. Trends are sampled when vram_status() reads the GPU;
there is no background sampler. See diagnostics.
The client's MCP schema provides full arguments and defaults.
Tool | Purpose |
| Inspect GPU memory, models, claims, activity, and pressure. |
| List resident models and their claim/busy details. |
| Try to reach a free-memory target by unloading unprotected models. |
| Evict a named model, respecting claims and recent activity. |
| Load a model for a chosen |
| Declare model use or capacity needed for other GPU work. |
| Extend or end your claim or reservation. |
| See active model claims and capacity reservations. |
| Review recorded actions, observed changes, and memory samples. |
| Get configuration suggestions; no settings are changed. |
Guide | Read it for |
Source installation, environment variables, and connection troubleshooting. | |
Claims, reservations, protection limits, pressure, and audit history. |
git clone https://github.com/sushiHex/vram-mcp.git
cd vram-mcp
python -m venv .venvActivate with source .venv/bin/activate on Linux or
.\.venv\Scripts\Activate.ps1 in PowerShell, then run:
python -m pip install -e ".[dev]"
python -m pytest -qTests use mocked GPU, process, and HTTP calls; no GPU or Ollama daemon is needed. CI covers Python 3.10–3.14 on Windows and Linux. Current model management targets Ollama and NVIDIA; AMD/Intel telemetry and vLLM/llama.cpp management are future work.
MIT — see LICENSE. Companion project: hardline-mcp for agent messaging.
Suggest env/config changes to keep VRAM healthy (heuristics).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states that it 'suggests' changes, which implies a non-mutating action, but it does not explicitly say it is read-only, nor does it describe the output format, whether it performs any analysis, or how the heuristics work. The agent cannot anticipate side effects or data returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the core purpose without unnecessary words. It is front-loaded with the primary action ('Suggest') and resource, making it easy to scan. It earns full credit for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should explain what the tool returns. It does not mention whether it returns a list, a message, or structured advice. It also lacks details on the nature of the heuristics or any examples. This leaves the agent with insufficient information to fully understand the tool's behavior or output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to elaborate on any. According to the rubric, a baseline of 4 is appropriate when there are no params. The description aligns with the schema, which has an empty properties object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Suggest') and resource ('env/config changes') with a clear purpose ('to keep VRAM healthy'). It uses 'heuristics' to indicate the nature of the suggestions. However, it could be more specific about the types of changes (e.g., environment variables, configuration files) and the format of suggestions, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings. The description does not mention any conditions, prerequisites, or alternatives such as `ensure_free` or `vram_status`. An agent is left to infer that this is an advisory tool, but there is no explicit direction on when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare that you're using model for purpose.
Lets other sessions see who's using a model and why before deciding to
evict it. Renew before ttl_seconds elapses if still in use — an
un-renewed claim simply expires, so a crashed session never leaves a
permanently-stuck claim.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| owner | Yes | ||
| purpose | Yes | ||
| ttl_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers meaningful detail: claims expire if not renewed, so crashed sessions do not leave stuck claims, and other sessions can see the claim before eviction. It does not cover conflict behavior or what happens if the same model is claimed twice, but the key lifecycle behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the core declaration, and uses the second sentence to explain the crucial expiry behavior without wasted words. Every sentence adds value and the structure flows logically from action to rationale.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple claim tool with no output schema and no annotations, the description covers the core call, the visibility rationale, and the expiration behavior. It could add what the call returns or how conflicts with existing claims are handled, but the essential information for invoking it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters, and it largely does: `model` and `purpose` are directly named in the declaration, `owner` maps to 'who's using', and `ttl_seconds` is tied to expiration timing. It does not fully define owner uniqueness or TTL precision, but it adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Declare') and names both the resource (`model`) and the intent (`purpose`), making the tool's function immediately clear. It also distinguishes itself from siblings by framing claims as visible declarations used to coordinate eviction, which sets it apart from renew, release, and list_claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this when actively using a model and wanting other sessions to know before eviction. It also implies the alternative tool (`renew`) by instructing to renew before ttl_seconds elapses, though it does not explicitly name when not to use it or mention `release` as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free VRAM until at least gb GB is available. Skips claimed/busy models
unless force=True. by records the requester in the audit log.
Also reports reserved_mb — how much of the resulting free VRAM other
sessions have reserved for non-Ollama work (None if unreadable).
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | unknown | |
| gb | Yes | ||
| force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does meaningful work: it discloses that claimed/busy models are skipped unless force=True, that by writes to the audit log, and that reserved_mb can be None if unreadable. It does not describe failure behavior when enough VRAM cannot be freed, but the core side effects are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences; the main action is front-loaded, followed by parameter semantics and the return signal. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It explains the return signal (reserved_mb, with a None fallback), which matters because there is no output schema. It could add failure semantics, such as what happens if the target cannot be reached, but the essential invocation details are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description defines all three parameters: gb as the target free amount, force as the override for claimed/busy models, and by as the audit-log requester. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Free VRAM until at least gb GB is available.' It also adds distinguishing behavior ('Skips claimed/busy models unless force=True'), making it easy to tell apart from siblings like unload, release, and reserve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: call when you need a guaranteed amount of free VRAM, with force controlling whether claimed/busy models may be displaced. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The VRAM audit trail, newest first: who ran unload/ensure_free/warm, and
which models/processes appeared or disappeared (with a best-effort cause).
Filter by model, type (action|disappeared|appeared), limit, or an
ISO since floor. Answers 'what happened to model X?'.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| model | No | ||
| since | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It specifies that the trail is newest first, includes a best-effort cause, and lists event types (action|disappeared|appeared). It does not mention aspects like response format, pagination, or performance, but it gives a solid behavioral overview sufficient for a read-only audit tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose ('VRAM audit trail, newest first'), followed by what it records and filters. Every sentence adds value: the cause detail, filter options, and the direct question it answers. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (4 optional params, no required fields, no output schema), the description is fairly complete for a read-only history tool. It explains what the data is, filters available, and the kind of question it answers. However, it lacks specifics on return format or how to interpret the 'cause' field, which might be needed for advanced use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions filtering by model, type, limit, and since, but provides minimal extra detail beyond the schema property names. For example, it explains 'since' as an ISO floor, which is useful, but does not elaborate on accepted formats for 'type' or 'model', leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving the VRAM audit trail, sorted newest first, showing actions like unload/ensure_free/warm and model/process appearance/disappearance with causes. It explicitly mentions filtering by model, type, limit, and since, and answers a specific question ('what happened to model X?'), which distinguishes it from sibling tools like vram_status or list_loaded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for auditing historical events and answering questions about changes, but it does not explicitly state when to use this tool versus alternatives like vram_status or trend. It provides some context (audit trail) but lacks explicit when-to-use or when-not-to-use guidance relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See who's claiming what right now (all models, or one).
| Name | Required | Description | Default |
|---|---|---|---|
| model | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. The casual 'See who's claiming what' implies a read-only operation but discloses no return format, pagination, or operational caveats. For a tool with zero annotation coverage, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded clause with zero waste. Verb, resource, temporal scope, and model-filter semantics are all packed into one short sentence; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-optional-parameter list tool, the description covers purpose and the model filter adequately. However, with no annotations and no output schema, the return shape of 'who's claiming what' is entirely unspecified — an agent won't know what fields the result contains. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate — and it does. The '(all models, or one)' parenthetical meaningfully explains that null means all models and a value filters to a single model, semantics the bare schema (string|null, default null) doesn't convey. Good compensation for the one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'See who's claiming what right now' — a specific verb (list/view) plus resource (current claims). The 'right now' qualifier implicitly distinguishes it from siblings like history and trend, but no sibling is named explicitly, so it stays at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'right now' phrasing implies current-state usage versus past-state siblings (history, trend), and 'all models, or one' hints at the model filter. But there is no explicit when-to-use / when-not-to-use guidance and no named alternatives — usage context is implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the models currently resident in VRAM, with claim/busy detail.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. 'List' implies a non-mutating read operation, and 'claim/busy detail' names the returned state, but it does not explicitly state the absence of side effects, how claim/busy is determined, or any blocking/load behavior. Adequate but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and resource, then adds the key detail. Every word earns its place; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list operation, the description covers the core semantics: what is listed and what detail is included. However, because there is no output schema or annotations, 'claim/busy detail' remains somewhat vague, and no sibling routing is provided. Still, the tool is simple enough that an agent can invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter semantics, but none are necessary for invocation; the empty schema already covers this completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with the imperative 'List' and identifies the specific resource ('models currently resident in VRAM'), plus a distinguishing output detail ('claim/busy detail'). This clearly separates it from sibling tools like list_claims, which likely lists claim records rather than VRAM-resident models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance and names no alternatives or exclusions. With siblings like list_claims, vram_status, and ensure_free, an agent must infer when this tool is the right choice, rather than being directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a claim early, before its TTL would expire.
| Name | Required | Description | Default |
|---|---|---|---|
| claim_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that this is an early mutation, with no details on side effects, failure states, or whether release frees resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one front-loaded sentence with no filler; every word contributes the core action and timing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool, the action and target are present, so it is minimally viable. However, with no annotations and no output schema, the absence of behavioral or postcondition detail leaves gaps about what 'release' actually changes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description never mentions claim_id. The term 'claim' in the description loosely maps to the required claim_id, but no format, source, or usage detail is added beyond the schema's type and name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Release') and resource ('claim'), and adds temporal scope ('early, before its TTL would expire'), so an agent can identify the action. It does not name sibling tools such as renew or unload, but the claim/TTL framing makes the operation distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage condition: use this when releasing a claim before TTL expiry. It does not explicitly state exclusions or compare with siblings, but the 'early' qualifier gives enough context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extend an existing claim's expiry before it lapses.
| Name | Required | Description | Default |
|---|---|---|---|
| claim_id | Yes | ||
| ttl_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool extends an existing claim's expiry, implying a mutation, but it does not disclose failure modes (e.g., what happens if the claim does not exist or has already lapsed), side effects, idempotency, or permissions. This is minimal coverage for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is efficient and front-loaded with the core purpose. However, it is under-specified for a tool with two parameters and a mutation side effect; while not verbose, it lacks necessary detail that would not make it overly long if added. It earns a 3 for being concise but not appropriately sized for the information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with two parameters, no output schema, and no annotations, the description is critically incomplete. It does not explain the ttl_seconds parameter, does not describe error conditions (e.g., non-existent claim, already lapsed), does not state whether the operation is reversible, and gives no context about the return value or side effects. The description is far from sufficient for an agent to call the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention either parameter. 'claim_id' is self-explanatory from its name, but 'ttl_seconds' is completely unexplained—its purpose, format, default behavior, and interaction with the claim's expiry are all unclear. The description adds no value beyond the bare schema, so it fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'extend' and the resource 'existing claim's expiry', which distinguishes it from sibling tools like 'claim' or 'reserve' that likely create new claims. The phrase 'existing claim' implies it operates on a claim that already exists, giving it a distinct purpose. However, it does not explicitly contrast with siblings, so it is not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used to extend a claim before it lapses, providing a timing condition, but it gives no explicit guidance on when to use this tool versus alternatives like 'claim', 'reserve', or 'release'. There are no exclusions or alternative references, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reserve gb GB of VRAM — a claim on capacity, not on a named model.
Use this for non-Ollama GPU work (a training run, a diffusion job) so other
sessions can see the VRAM is spoken for. pid is advisory. Reservations
expire by TTL like claims, so a crashed session never leaves one stuck.
COOPERATIVE: this gates vram-mcp's own warm(), but vram-mcp cannot
intercept an Ollama auto-load triggered by a direct /api/generate call
from another process.
| Name | Required | Description | Default |
|---|---|---|---|
| gb | Yes | ||
| pid | No | ||
| owner | Yes | ||
| purpose | Yes | ||
| ttl_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers: it discloses that pid is advisory, that reservations expire by TTL so crashed sessions never leave a stuck reservation, and the COOPERATIVE note explains both that it gates vram-mcp's own warm() and that it cannot intercept a direct Ollama /api/generate call from another process. This is rich, honest behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded paragraphs. The first line states the core purpose; the second gives the use case; the third gives essential limitation context. Every sentence earns its place and there is no filler or restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no annotations and no output schema, the description covers purpose, use case, TTL behavior, pid semantics, and cooperative limits. The main gap is the return value — what the reservation call produces (likely an ID needed by the renew/release siblings) is never stated, which an agent would want to know to chain calls correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains gb (VRAM amount), pid (advisory), and ttl_seconds (expiry semantics). Owner and purpose are not explicitly described but are self-evident by name. It adds meaning beyond the bare schema for three of the five parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair — 'Reserve gb GB of VRAM' — and immediately clarifies scope with 'a claim on capacity, not on a named model.' This distinguishes it from the sibling claim tool, which presumably targets a named model. An agent can tell them apart without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it — 'for non-Ollama GPU work (a training run, a diffusion job)' — so other sessions can see VRAM is spoken for. It doesn't name the alternative tool explicitly (claim) but implies it via 'not on a named model,' which is a clear enough exclusion for a competent agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-VRAM trend over the last hours, from the sampled audit log.
Answers "was this a gradual erosion or a sudden spike?" — the question a
point-in-time vram_status() cannot. Returns direction, min/max/latest
free MB (latest is null when the newest sample carries no reading),
how many samples showed driver spill, and the raw samples.
samples holds at most the 200 most recent rows so a long window can't
flood the caller's context; samples_truncated says whether older rows
were dropped. Every summary figure is computed over the FULL window either
way.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the return structure (direction, min/max/latest, spill count, raw samples), edge cases (latest is null when the newest sample lacks a reading), and truncation behavior (samples limited to 200 rows, samples_truncated flag, and summaries over the full window). This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the core purpose, then details the output and truncation behavior. Every sentence adds useful information, and the formatting (backticks, line breaks) aids readability. It is slightly longer than necessary but not padded, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must explain return values, which it does in detail. It covers the main purpose, all output fields, an edge case, and the truncation mechanism. For a tool of this complexity, nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is 'hours' with a default of 1, and the schema provides no description (coverage 0%). The description mentions 'over the last hours' but does not elaborate on units, range, or whether fractional hours are allowed. It adds minimal value beyond the parameter name itself. Since the description does not fully compensate for the schema gap, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports a free-VRAM trend over a time window, with specific outputs (direction, min/max/latest, spill samples, raw samples). It explicitly differentiates itself from vram_status(), a point-in-time tool, so an agent can select it correctly. The verb 'trend' plus the resource (free VRAM) and time window make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to answer whether VRAM change was gradual or sudden, contrasting with vram_status() which cannot. It also gives guidance on sample truncation to manage context. However, it does not mention other alternatives like history() or ensure_free(), but the primary distinction is clear. It implies use when you need trend analysis rather than a snapshot.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evict a single model from VRAM now (Ollama keep_alive=0).
Refuses by default if model has an active claim or a best-effort busy
signal — pass force=True to override (busy is windowed and can lag a few
seconds past a generation). by records who requested the eviction in the
audit log (see history).
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | unknown | |
| force | No | ||
| model | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses refusal conditions, the force override, the windowed/busy-signal lag, and the audit-log side effect of 'by.' It leaves some blind spots such as auth requirements, exact return behavior, and what happens if the model is not loaded, but the core mutating behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler. The primary action is front-loaded, followed by refusal/override semantics and the audit side effect. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a 3-parameter schema, the description covers the action, key edge cases, and side effects well. It is slightly incomplete because it does not explain what happens for an already-unloaded model, does not describe return/error values, and does not route between closely related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains force as an override for refusals and by as the audit-log actor; model is implicitly clear as the model being evicted, though its allowed format or identifier is not explicitly described. This is strong compensation for an uncovered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Evict a single model from VRAM now,' and maps it to Ollama's keep_alive=0, making the action concrete. It does not explicitly differentiate itself from siblings like release or ensure_free, though 'single model from VRAM' narrows the scope considerably.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames when to use the tool: when an immediate, single-model VRAM eviction is needed. It also gives an implicit when-not by describing refusal on active claims or busy signals and the force override, but it never names alternative tools or explicitly says 'use X instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the selected GPU and server-wide Ollama model residency.
Includes device identity, source health/timestamps/coverage, claims, recent GPU activity, and pressure (ok|tight|degraded|thrashing|unknown). Unavailable residency is null; unavailable telemetry never establishes an empty or healthy GPU. Non-local memory pressure is a best-effort paging heuristic.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that unavailable residency is null and that non-local memory pressure is a best-effort heuristic. However, it does not explicitly state the tool is read-only, mention error conditions, or performance implications, which are important for a monitoring tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the main purpose in the first sentence and supporting details following. It avoids redundancy and every sentence adds information about scope or behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description must convey what the tool returns. It lists the key content areas (device identity, health/timestamps, claims, activity, pressure) and explains null handling. This is sufficient for an agent to know what to expect, though exact formatting is not specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is effectively 100%. There is nothing for the description to add about parameters. Baseline for zero-parameter tools is 4, and the description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports GPU and server-wide model residency, with a specific verb ('report') and resource. It enumerates what is included (device identity, health, claims, activity, pressure). However, it does not explicitly distinguish itself from sibling tools like list_claims or list_loaded, though the scope is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention use cases, conditions, or exclusions, leaving the agent to infer when a status report is appropriate despite the presence of many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a model or refresh its keep-alive (e.g. "5m"; "-1" pins indefinitely).
An already resident model requires zero additional capacity. New loads account for reservations using an approximate model size; size_verified describes that estimate, while outcome describes verified residency. Returns succeeded|refused|failed|unknown. On unknown, inspect residency and pending_until before retrying. force=True bypasses admission checks but cannot override a pending operation. Zero durations must use unload().
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | unknown | |
| force | No | ||
| model | Yes | ||
| keep_alive | No | 5m |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it explains capacity accounting, the uncertainty of size estimates, possible outcomes (succeeded|refused|failed|unknown), retry guidance, and force behavior. This is unusually rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded, opening with the core action and immediately providing practical examples. Every sentence contributes: capacity, return states, retry guidance, force limitations, and the unload alternative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 0% parameter description coverage, this description is remarkably complete. It covers return semantics, edge cases, force constraints, keep-alive behavior, and even directs zero-duration cases to unload().
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains keep_alive format with examples like '5m' and '-1' and gives force semantics, adding real meaning beyond the schema. However, the 'by' parameter is never described, leaving one optional parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action with resource: 'Load a model or refresh its keep-alive.' It is specific and meaningful, but it does not explicitly distinguish warm from siblings such as renew or claim, leaving some potential overlap unaddressed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage context: resident models need no capacity, keep-alive formats are explained, and 'Zero durations must use unload()' provides an explicit when-not-to-use alternative. It does not, however, compare warm with other siblings like renew or advise.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0adviseclaimensure_freehistorylist_claimslist_loadedreleaserenewreservetrendunloadvram_statuswarmScored across 13 tools
Each tool targets a distinct operation: claim/renew/release manage claims, reserve handles capacity reservations, unload/ensure_free/warm manage model residency, while vram_status/list_loaded/list_claims/history/trend provide distinct read views. Even similar actions like unload vs ensure_free are clearly separated by scope (single model vs threshold-based eviction).
Naming uses a mix of bare verbs (renew, release, advise, unload, warm, claim, reserve), verb_noun snake_case (list_claims, list_loaded, ensure_free), and noun-only identifiers (vram_status, history, trend). The pattern is somewhat predictable by category (actions vs queries), but it lacks a single consistent convention, making it less uniform than an all-verb_noun set.
13 tools is well within the ideal 3–15 range and each tool addresses a meaningful aspect of VRAM management: claims, reservations, eviction, warming, status, history, and trend. No tool feels redundant or superfluous.
The surface covers the core lifecycle well: claim/renew/release, reserve, warm/unload/ensure_free, plus status, history, and trend. A minor gap is the lack of a dedicated list_reservations tool—list_claims seems focused on model claims, so capacity reservations may be invisible unless they appear in status/history.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Will this LLM fit on your GPU, multi-GPU rig or Mac? Exact VRAM & KV-cache math. Read-only.
MemoryOracle - 10 agent memory tools: vector store, recall, summarization, redaction.