Skip to main content
Glama

ensure_free

Free NVIDIA GPU VRAM by unloading Ollama models until at least the requested GB is available, skipping busy models unless forced, so new models can load.

Instructions

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).

Input Schema

NameRequiredDescriptionDefault
byNounknown
gbYes
forceNo

Output Schema

NameRequiredDescriptionDefault
okYes
modelYes
detailYes
reasonYes
free_mbYes
outcomeYes
summaryYes
attemptsYes
declinedYes
unloadedYes
target_mbYes
reserved_mbYes
retry_afterYes
already_freeYes
observationsYes
pending_untilYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$defs": {
      +    "ClaimEntry": {
      +      "properties": {
      +        "claim_id": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Claim Id"
      +        },
      +        "claimed_at": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Claimed At"
      +        },
      +        "expires_at": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Expires At"
      +        },
      +        "gb": {
      +          "anyOf": [
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Gb"
      +        },
      +        "kind": {
      +          "enum": [
      +            "model",
      +            "reservation"
      +          ],
      +          "title": "Kind",
      +          "type": "string"
      +        },
      +        "model": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Model"
      +        },
      +        "owner": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Owner"
      +        },
      +        "pid": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Pid"
      +        },
      +        "purpose": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Purpose"
      +        },
      +        "renewed_at": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Renewed At"
      +        },
      +        "ttl_seconds": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Ttl Seconds"
      +        }
      +      },
      +      "required": [
      +        "claim_id",
      +        "kind",
      +        "model",
      +        "gb",
      +        "pid",
      +        "owner",
      +        "purpose",
      +        "claimed_at",
      +        "renewed_at",
      +        "ttl_seconds",
      +        "expires_at"
      +      ],
      +      "title": "ClaimEntry",
      +      "type": "object"
      +    },
      +    "OperationEntry": {
      +      "properties": {
      +        "expires_at": {
      +          "title": "Expires At",
      +          "type": "string"
      +        },
      +        "kind": {
      +          "title": "Kind",
      +          "type": "string"
      +        },
      +        "lease_expired": {
      +          "title": "Lease Expired",
      +          "type": "boolean"
      +        },
      +        "lifecycle": {
      +          "enum": [
      +            "in_flight",
      +            "unknown",
      +            "unrecognized"
      +          ],
      +          "title": "Lifecycle",
      +          "type": "string"
      +        },
      +        "model": {
      +          "title": "Model",
      +          "type": "string"
      +        },
      +        "operation_id": {
      +          "title": "Operation Id",
      +          "type": "string"
      +        },
      +        "outcome": {
      +          "anyOf": [
      +            {
      +              "const": "unknown",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Outcome"
      +        },
      +        "owner_live": {
      +          "title": "Owner Live",
      +          "type": "boolean"
      +        },
      +        "pending_until": {
      +          "title": "Pending Until",
      +          "type": "string"
      +        },
      +        "reason": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Reason"
      +        },
      +        "retry_after": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Retry After"
      +        },
      +        "retry_count": {
      +          "title": "Retry Count",
      +          "type": "integer"
      +        },
      +        "scope": {
      +          "title": "Scope",
      +          "type": "string"
      +        },
      +        "started_at": {
      +          "title": "Started At",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "operation_id",
      +        "model",
      +        "kind",
      +        "scope",
      +        "started_at",
      +        "expires_at",
      +        "pending_until",
      +        "lifecycle",
      +        "owner_live",
      +        "lease_expired",
      +        "outcome",
      +        "reason",
      +        "retry_count",
      +        "retry_after"
      +      ],
      +      "title": "OperationEntry",
      +      "type": "object"
      +    },
      +    "ResidencyResult": {
      +      "properties": {
      +        "additional_mb": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Additional Mb"
      +        },
      +        "busy": {
      +          "anyOf": [
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Busy"
      +        },
      +        "claims": {
      +          "anyOf": [
      +            {
      +              "items": {
      +                "$ref": "#/$defs/ClaimEntry"
      +              },
      +              "type": "array"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Claims"
      +        },
      +        "coordination_warning": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Coordination Warning"
      +        },
      +        "detail": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Detail"
      +        },
      +        "free_mb": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Free Mb"
      +        },
      +        "headroom_mb": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Headroom Mb"
      +        },
      +        "keep_alive": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Keep Alive"
      +        },
      +        "model": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Model"
      +        },
      +        "model_size_mb": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Model Size Mb"
      +        },
      +        "observations": {
      +          "anyOf": [
      +            {
      +              "additionalProperties": true,
      +              "type": "object"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Observations"
      +        },
      +        "ok": {
      +          "title": "Ok",
      +          "type": "boolean"
      +        },
      +        "operation_id": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Operation Id"
      +        },
      +        "operations": {
      +          "anyOf": [
      +            {
      +              "items": {
      +                "$ref": "#/$defs/OperationEntry"
      +              },
      +              "type": "array"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Operations"
      +        },
      +        "outcome": {
      +          "enum": [
      +            "succeeded",
      +            "refused",
      +            "failed",
      +            "unknown"
      +          ],
      +          "title": "Outcome",
      +          "type": "string"
      +        },
      +        "pending_until": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Pending Until"
      +        },
      +        "protected": {
      +          "anyOf": [
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Protected"
      +        },
      +        "reason": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Reason"
      +        },
      +        "refused": {
      +          "anyOf": [
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Refused"
      +        },
      +        "reservations": {
      +          "anyOf": [
      +            {
      +              "items": {
      +                "$ref": "#/$defs/ClaimEntry"
      +              },
      +              "type": "array"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Reservations"
      +        },
      +        "reserved_mb": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Reserved Mb"
      +        },
      +        "resident": {
      +          "anyOf": [
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Resident"
      +        },
      +        "retry_after": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Retry After"
      +        },
      +        "retry_count": {
      +          "title": "Retry Count",
      +          "type": "integer"
      +        },
      +        "scope": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Scope"
      +        },
      +        "size_verified": {
      +          "anyOf": [
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "title": "Size Verified"
      +        },
      +        "summary": {
      +          "title": "Summary",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "ok",
      +        "outcome",
      +        "model",
      +        "reason",
      +        "detail",
      +        "summary",
      +        "operation_id",
      +        "pending_until",
      +        "retry_after",
      +        "retry_count",
      +        "keep_alive",
      +        "resident",
      +        "protected",
      +        "busy",
      +        "claims",
      +        "operations",
      +        "observations",
      +        "reservations",
      +        "refused",
      +        "size_verified",
      +        "model_size_mb",
      +        "headroom_mb",
      +        "reserved_mb",
      +        "additional_mb",
      +        "scope",
      +        "free_mb",
      +        "coordination_warning"
      +      ],
      +      "title": "ResidencyResult",
      +      "type": "object"
      +    }
      +  },
      +  "properties": {
      +    "already_free": {
      +      "title": "Already Free",
      +      "type": "boolean"
      +    },
      +    "attempts": {
      +      "items": {
      +        "$ref": "#/$defs/ResidencyResult"
      +      },
      +      "title": "Attempts",
      +      "type": "array"
      +    },
      +    "declined": {
      +      "items": {
      +        "additionalProperties": true,
      +        "type": "object"
      +      },
      +      "title": "Declined",
      +      "type": "array"
      +    },
      +    "detail": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Detail"
      +    },
      +    "free_mb": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Free Mb"
      +    },
      +    "model": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Model"
      +    },
      +    "observations": {
      +      "additionalProperties": true,
      +      "title": "Observations",
      +      "type": "object"
      +    },
      +    "ok": {
      +      "title": "Ok",
      +      "type": "boolean"
      +    },
      +    "outcome": {
      +      "enum": [
      +        "succeeded",
      +        "refused",
      +        "failed",
      +        "unknown"
      +      ],
      +      "title": "Outcome",
      +      "type": "string"
      +    },
      +    "pending_until": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Pending Until"
      +    },
      +    "reason": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Reason"
      +    },
      +    "reserved_mb": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Reserved Mb"
      +    },
      +    "retry_after": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Retry After"
      +    },
      +    "summary": {
      +      "title": "Summary",
      +      "type": "string"
      +    },
      +    "target_mb": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Target Mb"
      +    },
      +    "unloaded": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "title": "Unloaded",
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "ok",
      +    "outcome",
      +    "model",
      +    "reason",
      +    "detail",
      +    "summary",
      +    "pending_until",
      +    "retry_after",
      +    "already_free",
      +    "free_mb",
      +    "unloaded",
      +    "declined",
      +    "attempts",
      +    "target_mb",
      +    "reserved_mb",
      +    "observations"
      +  ],
      +  "title": "EnsureFreeResult",
      +  "type": "object"
      +}
  2. First observedv0.2.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does well: it discloses that claimed/busy models are skipped by default, that force overrides that safeguard, and that 'by' writes to an audit log. It stops short of stating destructiveness (whether models are unloaded/killed), permissions required, or whether the call blocks until the target is met.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action in the first sentence and uses two terse follow-ups for the skip/force rule, audit attribution, and reserved_mb. The reserved_mb sentence borders on restating the output schema, but adds interpretation ('reserved for non-Ollama work') that the schema alone would not convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description is not obligated to explain return values, and its brief reserved_mb note is a bonus rather than a gap-filler. What remains thin is the mutation profile — whether freeing VRAM evicts models, what happens if the target cannot be reached, and whether the call is blocking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must supply all parameter meaning, and it does: gb is the target free GB threshold, force overrides the claimed/busy skip, and by records the requester in the audit log. Every one of the three parameters is semantically explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Free VRAM) plus a quantified goal condition (until at least gb GB is available), which is far more precise than a bare name restatement. It tacitly differentiates from siblings like unload and vram_status by being goal-directed rather than model-specific or observational, though it never names them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear usage condition for the force flag (skips claimed/busy models unless force=True), which implies when to reach for it. However, it never states when to prefer ensure_free over unload, claim, or vram_status, so the agent must infer the routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.