The AI Guardian server provides observability, content governance, and policy enforcement for local LLMs (Ollama, llama.cpp, LM Studio, vLLM). You can:
Monitor models and server: List installed and running models, check VRAM usage, view model details (license, parameters, capabilities), verify server status and version, and detect shadow/unsanctioned models.
Govern content: Scan prompts for secrets, PII, source code, and jailbreak attempts (offline, no model call). Assign risk bands and route prompts through a guard that blocks high-risk or disallowed requests.
Manage model policies: Set allow/deny lists (glob patterns), pin provenance digests to detect drift/tampering, and enforce policies for model pulls, runs, and removals.
Control model lifecycle: Pull, remove, or unload models (removals support dry-run and undo). All operations respect policies.
Audit and detect anomalies: Query usage events with filters; generate reports on shadow models, drift, high-risk prompts, and blocked calls.
Undo reversible actions: Record undo tokens for allowlist changes, removals, etc., and apply them (dry-run supported).
Proxy transparent capture: Use the proxy to apply governance to clients that don’t natively integrate the guard.
All operations are audited, risk-tiered, and governed with undo recording.
Provides observability and governance for local LLMs running on Ollama, including model inventory, content scanning, and policy-enforced prompt routing.
Click on "Install 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., "@AI Guardian list all installed models"
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.
Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by Ollama, IGEL, or any AI-security vendor. Product and trademark names belong to their owners. MIT licensed.
Governed observability + governance for on-endpoint local LLMs. It lets you
observe + audit what your local models are actually fed, and gate what leaves in
a prompt — the complement to IGEL AI Armor. AI Armor governs whether a
local model may run on the endpoint; ai-guardian records what it did and gates
what goes into the prompt (secrets, PII, source, jailbreaks) plus which model
may serve it. Self-contained: it talks to each runtime's REST API and needs
nothing beyond httpx and the MCP SDK. v0.1 provides opt-in route-through
content governance, plus a transparent capture proxy for clients that did not opt in.
One tool, several local runtimes, selected per target by a runtime field in
config.yaml (the init wizard asks). Ollama uses its native API; the other three
share one OpenAI-compatible transport (/v1/models + /v1/chat/completions).
Runtime |
| Default port | List / policy | Scan + route-through guard | Provenance |
Ollama |
| 11434 | ✅ | ✅ | digest (content hash — strong) |
llama.cpp ( |
| 8080 | ✅ | ✅ | props — |
LM Studio |
| 1234 | ✅ | ✅ | id only — weaker; pins report |
vLLM (local single-node) |
| 8000 | ✅ | ✅ | id only — weaker; pins report |
The allow/deny model policy, the deterministic prompt scanner, the route-through
guard (guarded_generate / observe_chat), provenance drift, and doctor work
across all runtimes. Model lifecycle writes (pull / remove / unload)
are Ollama-only — the OpenAI-compatible servers load a model at startup and expose
no lifecycle endpoint, so those writes are refused with a clear message.
Provenance honesty: only Ollama (content digest) and llama.cpp (a /props-derived
path/size identity) expose something to pin. LM Studio and vLLM expose only a model
id, so a pinned digest is reported unverifiable rather than a false DRIFT.
vLLM here is a LOCAL endpoint-guarding use case. GPU inference-cluster operations (autoscale, drain, Ray Serve/Jobs, model lifecycle at fleet scale) belong to a different tool in the line — GPU cluster ops → inference-aiops.
Ollama persists no queryable prompt/response history — conversational context is client-supplied on every request. So ai-guardian observes on two fronts:
Passive inventory / state auditing — over /api/tags, /api/ps,
/api/show, /api/version: what models are installed and running, their VRAM
residency, license/params/capabilities, and their provenance digests. Every
model is annotated with an allow/deny policy verdict, so shadow
(unsanctioned) models show allowed: false.
Opt-in route-through content governance — callers send a prompt through
ai-guardian (guarded_generate / observe_chat). It scans the text
(secrets / PII / source / jailbreak), checks the model against policy,
records the interaction to its own usage log (~/.ai-guardian/usage.db),
and only then calls Ollama — blocking when the risk band is too high or the
model is disallowed. The raw prompt is never stored (only its length + redacted
findings).
Now available (
ai-guardian proxy serve): a transparent capture proxy that applies the same scan + model policy + recording to traffic from clients that never opted in — point them at the proxy instead of the runtime. It inspects requests and streams responses through untouched, and it is a chokepoint, not an enforcement boundary: a client that can still reach the runtime's real port bypasses it entirely.proxy_guidancereturns the command and that caveat; the CLI prints it on every start.
Related MCP server: agent-sudo-mcp
Deterministic, offline prompt scanner — no I/O, no network, so it is fully
testable offline. Flags secrets (AWS AKIA, private-key blocks,
GitHub / Slack / OpenAI / Google tokens, JWTs, assigned api_key=…, high-entropy
fallback), PII (email, US SSN, credit card with a Luhn check),
source/config-leak heuristics, and jailbreak / prompt-injection
signatures — rolled up into a weighted risk band (low / medium / high /
critical; any critical dominates). Findings are redacted — the scanner never
re-emits the secret it caught.
Model allow/deny policy (shell-glob patterns) so shadow / unsanctioned
models surface as allowed: false, plus provenance digest pinning to flag a
model whose digest drifted (re-pulled / tampered).
Route-through guard — guarded_generate / observe_chat scan + policy-gate
record + run-if-allowed, blocking on risk-band >= block_threshold (default
high) or a disallowed model.
Vendored governance harness — audit log, token/runaway budget guard, descriptive risk tiers, and undo-token recording, bundled in the package (no external dependency).
Highly self-testable — Ollama is free + local for the API parts; the scanner, policy, and risk-band are pure deterministic offline logic.
It delivers local-LLM observability and operations — reads and writes — accurately, and records every one of them. It does not decide whether a write to the model estate is allowed to happen. That is the agent's judgement, or the permission of the host and account you run it under: point it at a runtime the account cannot administer — an Ollama daemon whose model store the user can't modify, or an endpoint the agent reaches read-only — and the writes fail at the runtime, the place that actually owns the permission. Simplest of all, hand the connecting agent only the scan/observe tools.
So the harness has no read-only switch, no deny-rules file, and no approval gate
to configure. (Content governance is a separate, product-level thing that stays:
the model allow/deny policy and the guarded_generate block threshold still
scan and gate what a model is asked to do.) The one thing the harness guarantees
is that nothing is silent: every call, over MCP and over the CLI alike, lands
an audit row in ~/.ai-guardian/audit.db, and destructive writes still capture
their before-state and record an inverse where one exists.
Each tool declares a
risk_level, kept in agreement with its[READ]/[WRITE]documentation tag by a test, and carried into the audit row as a descriptive tier — so a reviewer can see at a glance that a row was a high-risk delete. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
Tool | Risk | What it returns |
| low | installed models, each with the allow/deny verdict (shadow → |
| low | loaded models: VRAM footprint + residency expiry |
| low | license / parameters / capabilities for one model |
| low | Ollama reachability + version |
| low | total VRAM used by loaded models; flag over-budget |
| low | current allow/deny policy + provenance digest pins |
| low | each installed digest vs its pin; flag drift |
| low | pure text scan → findings + weighted risk band (no model call) |
| low | query the observed-usage log |
| low | rollup: shadow models, digest drift, high-risk + blocked prompts |
| low | the |
Tool | Risk | Undo / safety |
| medium | refused if it violates policy |
| high | dry-run + undo (re-pull) |
| medium | evict from VRAM ( |
| medium | undo → prior allowlist |
| medium | undo → prior denylist |
| medium | pin a model's expected provenance digest |
| medium | the route-through guard: scan + policy-gate + record + run-if-allowed |
| medium | same, for |
Tool | Risk | What it does |
| low | list recorded undo tokens |
| medium | replay a recorded inverse descriptor |
Risk-band gating: guarded_generate / observe_chat block when the prompt's
risk band >= block_threshold (default high) or the model is disallowed.
Blocked calls never reach Ollama and are recorded as blocked in the usage log.
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install ai-guardian@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with ai-guardian init — see below.
uv tool install ai-guardian-aiops # or: pipx install ai-guardian-aiops
ai-guardian doctor # Ollama reachability + policy summary (works zero-config)
ai-guardian overview # models installed/running, shadow count, usage stats
ai-guardian model list # installed models with allow/deny verdicts
ai-guardian guard scan "my key is AKIAIOSFODNN7EXAMPLE" # deterministic scan → risk bandRoute a prompt through the guard (scan + policy-gate + record + run-if-allowed) via MCP:
guarded_generate(model="llama3.2:3b", prompt="…", block_threshold="high")Run as an MCP server (stdio) — the full 21-tool surface; the CLI is a convenience subset:
export AI_GUARDIAN_AIOPS_MASTER_PASSWORD=... # only if a target has a stored token
ai-guardian mcp # or: ai-guardian-mcpEvery operation — MCP and CLI — passes through the bundled @governed_tool
harness. It records; it does not authorize (see above).
Audit — every call (params, result, status, duration, risk tier, and any
operator-supplied approver/rationale) is logged to ~/.ai-guardian/audit.db
(relocatable via AI_GUARDIAN_AIOPS_HOME). This is separate from
~/.ai-guardian/usage.db, which holds the observed local-LLM usage.
Runaway guard — a safety backstop, not an authorization gate: the same
call hammered in a tight loop trips a circuit breaker so a stuck agent can't
burn unbounded calls/time. Disable with AI_GUARDIAN_RUNAWAY_MAX=0; optional
hard ceilings via AI_GUARDIAN_MAX_TOOL_CALLS / AI_GUARDIAN_MAX_TOOL_SECONDS.
Undo recording — reversible writes record an inverse descriptor built from the fetched before-state.
Risk tier — a descriptive label on the audit row derived from
risk_level; it gates nothing.
Scope: on-endpoint local LLMs — Ollama plus the OpenAI-compatible llama.cpp / LM Studio / local single-node vLLM — single-endpoint local-LLM observability + content governance. Not GPU inference-cluster ops (→ inference-aiops).
v0.1 = passive inventory/state auditing plus opt-in route-through content governance. A transparent capture proxy for other clients' traffic is v0.2 roadmap, not v0.1.
IGEL AI Armor interop is doc-level positioning today (complementary roles), not a wired integration.
Validation status — the scanner, policy, and risk-band are pure
deterministic offline logic and are exercised as such by the test suite. The
core Ollama route-through (real generation + policy deny + undo capture) was
exercised against a live Ollama 0.24.0 on 2026-07-13; the rest of the Ollama
surface and the OpenAI-compatible dialects (llama.cpp / LM Studio / local
vLLM) are still covered by mocked responses only. ai-guardian doctor is the
fastest live check; see docs/VERIFICATION.md for
exactly which boxes are ticked.
Want a passive capture proxy, another scanner signature, a richer policy model, or an AI Armor hook? Open an issue or PR — feedback and contributions welcome.
[READ] Rollup: shadow models, digest drift, high-risk prompts, blocked count.
Args: target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only adds a '[READ]' tag. It does not disclose behavioral traits such as authentication needs, rate limits, data freshness, or side effects, leaving significant gaps for a tool that likely accesses sensitive metrics.
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 extremely concise, front-loading the critical '[READ]' tag followed by a clear list of metrics and a brief parameter explanation. Every sentence is purposeful and no words are wasted.
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 low complexity (one optional parameter, no output schema, read-only), the description is fairly complete: it states the purpose, lists reported items, and describes the parameter. However, it lacks details on output format or examples, which would improve completeness for an agent.
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 single optional parameter 'target' is explained with context ('Ollama target name from config; omit for the default'), which adds value beyond the input schema's minimal type definition. Schema coverage is 0%, so the description compensates well for this simple 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 clearly states it is a read operation ('[READ]') and lists the specific metrics reported ('shadow models, digest drift, high-risk prompts, blocked count'), making the purpose unambiguous. It distinguishes from sibling tools that also perform reads or actions by specifying a unique rollup report.
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 like server_status or list_models. The description does not specify scenarios, prerequisites, or exclusions, leaving the agent to infer usage without explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Scan + policy-gate a prompt, record it, then run if allowed.
The route-through guard: scans the prompt (secrets/PII/code/jailbreak), checks the model against policy, blocks if the risk band >= block_threshold or the model is disallowed, records the interaction to the usage log, and only calls Ollama if allowed. The raw prompt is never stored.
Args: model: Model to run. prompt: The prompt text (scanned before any model call). agent / user: Actor attribution recorded in the usage log. block_threshold: Block when risk band >= this (none/low/medium/high/critical). target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | ||
| agent | No | unknown | |
| model | Yes | ||
| prompt | Yes | ||
| target | No | ||
| block_threshold | No | high |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: scanning for secrets/PII/code/jailbreak, policy checking, blocking based on risk band, recording to usage log, and that the raw prompt is never stored. This is comprehensive for a guarded generation 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 well-structured with a header, a paragraph explaining the guard mechanism, and bullet points for args. It is slightly verbose but every sentence adds value, making it efficient for an agent.
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 description covers the process and parameters well but does not explain the return value or response format. Given no output schema, a brief mention of what the tool returns (e.g., success/error, generated text) would improve completeness.
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 schema has 0% description coverage, but the description provides meaningful explanations for each parameter (e.g., `model` is the model to run, `block_threshold` blocks when risk band >= this), adding value beyond the schema's titles.
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: a write operation that scans and policy-gates a prompt, records it, and runs Ollama if allowed. It distinguishes itself from siblings like `scan_prompt` which only scans without generation.
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 explains when to use the tool: when a prompt needs to go through the guard. It implies alternatives like `scan_prompt` for just scanning, but does not explicitly state when not to use it or name all alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Installed models, each annotated with the allow/deny policy verdict.
Shadow (unsanctioned) models show allowed: false.
Args: target: Ollama target name from config; omit for the default (local).
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It clearly states it's a read operation and explains output includes policy annotations. No contradictions, but could mention response structure or side effects.
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?
Description is very concise: three short lines covering purpose, output detail, and parameter. No wasted words, front-loaded with the read indicator.
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 list tool with one optional parameter and no output schema, the description covers the main purpose and parameter. It could mention if results are paginated or include model sizes, but overall sufficient.
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?
With 0% schema coverage, description compensates by explaining the 'target' parameter: its meaning (Ollama target from config) and default behavior (local). Adds significant clarity beyond the 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 clearly states it lists installed models with policy verdicts, distinguishing it from sibling tools like running_models. The verb and resource are specific.
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 explicit guidance on when to use this tool vs. alternatives like running_models or model_details. The description only explains the parameter, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] License / parameters / capabilities for one model.
Args: model: Model name (e.g. "llama3.2:3b"). target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral disclosure burden. It only indicates the tool is a 'READ' operation but fails to detail side effects, authentication requirements, rate limits, or any other behavioral traits. The lack of safety or mutability context is a significant 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?
The description is extremely concise, using two short sentences plus parameter definitions. The '[READ]' prefix quickly signals the tool's operation, and every sentence provides essential information without redundancy. The structure is front-loaded and efficient.
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 clarify the return format or structure. It mentions 'License / parameters / capabilities' but does not specify what data is returned or how to interpret it. This leaves uncertainty for the agent about the tool's output expectations.
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 define parameters. It adequately explains 'model' with an example ('llama3.2:3b') and 'target' with guidance ('Ollama target name from config; omit for the default'). This adds meaningful context beyond the bare schema, though it could be slightly more detailed about accepted formats or constraints.
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 'License / parameters / capabilities for one model' with a '[READ]' prefix, establishing a specific verb and resource. It differentiates from sibling tools like 'list_models' (all models) and 'running_models' (only running models) by focusing on a single model's details.
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?
Explicitly lists parameters with examples ('e.g. "llama3.2:3b"') and explains when to use them (omit target for default). While it lacks explicit exclusion of alternatives, the context of being a single-model detail retrieval is clear, and the sibling list provides natural comparison points.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Compare each installed model's digest against its pin; flag drift.
Args: target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool is a read operation and compares digests, but does not mention what happens on drift (e.g., generates a report, returns a list), any authorization needs, or side effects. It's adequate but could be more 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 very concise, with two sentences plus arg explanation. It is front-loaded with [READ] and the core action. Every sentence is meaningful without 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?
Given the tool's simplicity and lack of output schema, the description covers the primary functionality. However, it omits details about the output format (e.g., list of models with drift status) and any prerequisites (e.g., the model must be pinned). It is complete enough for a straightforward tool but has gaps.
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 description explains the 'target' parameter: 'Ollama target name from config; omit for the default.' This adds meaning beyond the schema's type and default. Although context shows 0% schema description coverage, the description effectively documents the 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 clearly states the tool's action: 'Compare each installed model's digest against its pin; flag drift.' The [READ] prefix indicates it's a read operation. It distinguishes itself from sibling tools like list_models or running_models by focusing on integrity validation.
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 checking model integrity, but it does not explicitly state when to use this tool versus alternatives (e.g., when to suspect tampering or after pulling models). No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Scan + policy-gate a chat exchange, record it, then run if allowed.
Args: model: Model to run. messages: OpenAI-style [{"role","content"}] messages (contents are scanned). agent / user: Actor attribution recorded in the usage log. block_threshold: Block when risk band >= this. target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | ||
| agent | No | unknown | |
| model | Yes | ||
| target | No | ||
| messages | Yes | ||
| block_threshold | No | high |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the tool is a write operation ([WRITE]) with medium risk, and outlines the flow (scan, policy-gate, record, run). However, it does not specify what happens when the policy blocks the chat (e.g., error vs. silent failure) or what exactly is recorded (e.g., usage log details). Additional behavioral context, such as side effects or authorization needs, would improve transparency.
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 very concise: a one-line purpose summary followed by a clean Args list. Every sentence adds value. No redundant or extraneous text. Front-loaded with the core action.
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 output schema, the description should hint at return values (e.g., model response, block status). It omits output expectations. Also, error handling or side effects of the recording are not mentioned. While parameters are well-covered, the overall user journey (what the agent gets back) is incomplete.
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%, so description must explain parameters. It does so for all 6: model (model to run), messages (OpenAI-style format), agent/user (actor attribution), block_threshold (threshold for blocking), target (Ollama target, omit for default). This adds rich functional meaning beyond schema field names and defaults.
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 starts with a clear verb+resource: 'Scan + policy-gate a chat exchange, record it, then run if allowed.' It distinctly differs from siblings like scan_prompt (scan only) and guarded_generate (generation with guard) by combining scanning, policy enforcement, recording, and execution in one step.
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: use when you want to run a chat through policy checks before execution. However, it does not explicitly state when not to use this tool or suggest alternatives (e.g., scan_prompt for just scanning, guarded_generate for generation without recording). Usage context is merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Pin a model's expected provenance digest (drift detection).
Args: model: Model name. digest: The expected digest to pin (from list_models / model_details).
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| digest | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden. It includes '[WRITE][risk=medium]' indicating a write operation with medium risk. However, it does not explain what pinning entails (e.g., reversibility, effect on existing pins), leaving behavioral gaps.
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?
Description is extremely concise, consisting of a single sentence plus a parameter list. The '[WRITE][risk=medium]' tag front-loads key information. No fluff.
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 2 required params and no output schema, the description explains the purpose and parameter sources but omits details on return values, error states, or prerequisites (e.g., model must exist). Adequate but not comprehensive.
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?
With 0% schema coverage, description adds meaning: it labels the 'digest' parameter as 'the expected digest to pin (from list_models / model_details)', providing source context. The 'model' parameter is only described as 'Model name', which is minimal but acceptable.
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 clearly states the action ('Pin'), resource ('model's expected provenance digest'), and purpose ('drift detection'). It distinguishes from sibling tools like list_models and model_details.
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 context by referencing where the digest comes from (list_models / model_details), but does not explicitly state when to use or not use this tool, nor mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] The current model allow/deny policy + provenance digest pins.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says '[READ]' and lists the content, but does not mention error conditions, caching behavior, or permission requirements. Minimal transparency.
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 sentence with a clear '[READ]' prefix. It is concise and front-loaded, but could benefit from slightly more structure, such as listing the two components separately.
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 read tool with no parameters and no output schema, the description provides the essential content (policy and pins). However, it lacks any hint of the response format or potential limitations, which slightly reduces completeness.
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 100% trivially. Per guidelines, baseline is 4. The description does not need to add parameter details.
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 it reads the current allow/deny policy and provenance digest pins. '[READ]' marks it as read-only, and the specific resource names distinguish it from sibling write tools like set_model_allowlist and pin_model_digest.
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 use for viewing current policy and pins, but does not explicitly state when to use it versus alternatives like list_models or set_model_allowlist. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] How to run the transparent capture proxy, and what it does NOT guarantee.
WRITES NOTHING and starts no listener — it composes the ai-guardian proxy serve command plus the client-side change, and returns the caveat that
matters: the proxy is a CHOKEPOINT, not an enforcement boundary. Any client
that can still reach the runtime's real port bypasses it entirely, and this
tool cannot detect that. Captured traffic is a sample, not the population,
until the runtime is unreachable except through the proxy.
Requests are scanned before forwarding; responses stream through uninspected, because buffering them would turn every streaming client into a blocking one. A governed request whose body cannot be parsed is refused, not forwarded.
Args: listen_host: Address the proxy would bind. listen_port: Port the proxy would bind (default 11435). target: Runtime target from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| listen_host | No | 127.0.0.1 | |
| listen_port | 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, and it excels. It explicitly states side effects (writes nothing, starts no listener), what it returns (composed command plus caveat), and important limitations like the proxy being a 'CHOKEPOINT, not an enforcement boundary' and the fact that responses stream uninspected. It also explains the parsing behavior for unparseable bodies.
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 somewhat lengthy but well-structured, front-loading with '[READ]' and then providing essential caveats and parameter details. Every sentence adds valuable context, though it could be tightened by moving some caveats to a separate section. It remains appropriately sized for the complexity of the tool.
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 description is complete for an informational tool. It covers the tool's action (composing a command), its non-action (no writes or listener), and its output (the caveat), along with critical behavioral specifics. No output schema exists, but the description sufficiently explains what the user gets. It also addresses proxy limitations and request handling, making it self-contained.
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 input schema has no property descriptions (coverage 0%), so the description must compensate. It does so with brief but meaningful explanations for each parameter: listen_host ('Address the proxy would bind'), listen_port ('Port the proxy would bind'), and target ('Runtime target from config; omit for the default'). This adds practical meaning beyond the schema's types and defaults.
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: it explains how to run the transparent capture proxy and what it does not guarantee, by composing a command and returning a caveat. It distinguishes itself from sibling tools by explicitly noting it 'WRITES NOTHING and starts no listener,' making it a guidance/informational tool rather than an action tool.
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?
Usage is implied rather than explicitly stated. The '[READ]' prefix and the note that it writes nothing indicate this is for guidance, not for execution, but there is no direct 'use this when' or 'use X instead' guidance. The description provides context but lacks explicit when/when-not or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Pull a model — refused if it violates the deny/allow policy.
Args: model: Model name to pull. target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only indicates write operation and policy check, lacking details on side effects, disk usage, or latency.
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?
Extremely concise; front-loaded with action and risk, then clear arg descriptions. No wasted words.
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?
Basic but misses behavioral context like download size, time, or post-pull effects; acceptable for a simple tool but could improve.
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?
Despite 0% schema coverage, description explains both parameters ('Model name to pull' and 'Ollama target name from config; omit for default'), adding value beyond schema types.
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 explicitly states 'Pull a model' with a policy refusal note, clearly distinguishing it from siblings like list_models or remove_model.
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 explicit when-to-use guidance or exclusion criteria; only mentions policy rejection but no alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=high] Delete a local model. Destructive — pass dry_run=True to preview.
Captures the model's manifest so the harness records an undo (re-pull).
An undo is recorded only when the allow/deny policy would permit re-pulling the model. For a denied one the result says reversible=false and explains why, rather than recording a re-pull that undo_apply is bound to refuse. The dry-run preview carries the same verdict, so the caller learns it before the deletion rather than after.
Args: model: Model name to delete. dry_run: If True, return what WOULD be deleted without deleting. target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| target | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses destructive nature, dry-run behavior, undo recording conditions (only if policy permits re-pull), and that dry_run carries the same verdict. This is comprehensive.
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?
Well-structured with a clear opening, behavioral context, then parameter definitions. Every sentence adds value; not overly verbose for the complexity exposed.
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?
Lacks explanation of the normal (non-dry-run) return value or output schema. Since no output schema exists, the description should clarify what the user receives upon deletion (e.g., success message or model details). Otherwise, coverage is solid.
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?
Despite 0% schema description coverage, the Args section in the description defines each parameter: model as required name, dry_run as boolean for preview, target as optional default host. Fully compensates for missing schema descriptions.
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 clearly states 'Delete a local model', distinguishing it from siblings like list_models (read-only), pull_model (download), and unload_model (unload from memory). The [WRITE][risk=high] prefix reinforces the purpose.
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 explicit guidance to use dry_run=True for previewing, and explains the undo recording behavior and policy implications. While it doesn't contrast with alternatives like unload_model, the context is sufficient for understanding when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Currently loaded models: VRAM footprint + residency expiry.
Args: target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly marks the tool as [READ], indicating read-only behavior. No annotations are provided, so the description carries the burden. It does not mention any side effects or permissions, but for a read-only tool, the behavior is sufficiently disclosed.
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 extremely concise: two lines with no superfluous text. The first line states the purpose, the second explains the parameter. Every word serves a purpose.
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 tool's simplicity (one parameter, no output schema), the description covers the essential: what it returns and how to parameterize. It could mention the return format (list or object), but the stated info (VRAM footprint + residency expiry) is sufficient.
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 schema has no descriptions (0% coverage), but the description adds meaning for the only parameter: 'target: Ollama target name from config; omit for the default.' This tells the agent what the parameter is and how to use it, compensating for the schema gap.
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 it reads currently loaded models and specifies the returned data (VRAM footprint + residency expiry). This is a specific verb-resource combination, and it distinguishes from siblings like list_models and vram_usage.
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 checking loaded models and mentions the target parameter from config. However, it does not provide guidance on when not to use this tool or when alternatives (like list_models) might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Pure content scan of a text for secrets / PII / code / jailbreak.
No Ollama call — a deterministic scan returning findings + a weighted risk band. Use it to pre-check anything before sending it to a local model.
Args: text: The text to scan.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the scan as pure content scan, deterministic, returning findings with risk band. Lacks details on detection methods or limitations, but adequate for a simple tool with no annotations.
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?
Description is short and front-loaded with '[READ]' to indicate nature. Minor formatting oddity (dash) does not detract. Could be slightly more structured but overall efficient.
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 deterministic scan with one parameter, the description fully covers purpose, usage, behavior, and parameter without needing output schema. No gaps given tool complexity.
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 description provides a brief parameter definition ('text: The text to scan'), which adds slight value beyond the schema. With 0% schema coverage, more detail would be beneficial, but the single parameter makes it acceptable.
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 tool name and description clearly indicate it scans text for secrets/PII/code/jailbreak. It specifies it's a deterministic read operation, distinguishing it from sibling tools that involve model calls.
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?
Explicitly states 'Use it to pre-check anything before sending it to a local model,' providing clear context. Also notes 'No Ollama call' to differentiate from generative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Ollama reachability + version.
Args: target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It indicates read-only via [READ] but does not describe side effects, error handling, or authentication requirements. The simple nature partially mitigates this, but more detail on behavior (e.g., what 'reachability' means) would improve transparency.
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 extremely concise with two lines and a param definition. It front-loads the key info [READ] and uses minimal words. Every sentence is necessary and no fluff.
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 status-check tool with one optional parameter and no output schema, the description covers the core behavior and parameter. However, it lacks information about the return value format (e.g., boolean, JSON) or error scenarios. Since there is no output schema, adding a brief note about the output would make it more 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 coverage is 0%, so the description must compensate. It explains the single parameter 'target' as an optional Ollama target name, with a default when omitted. This adds value beyond the schema. However, it does not clarify what the default target is, leaving some 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 checks Ollama reachability and version, using a [READ] prefix to indicate read-only. It distinguishes from siblings like list_models and running_models, which focus on models rather than server status. However, it could be more specific about the output.
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 explicit guidance on when to use this tool versus alternatives. The parameter description is present but does not provide context for selection among siblings. A statement like 'Use this to verify server connectivity before proceeding' would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Replace the model allowlist (glob patterns; empty = allow-all).
Args: models: Shell-glob patterns of permitted model names (e.g. ["llama3.", "qwen"]).
| Name | Required | Description | Default |
|---|---|---|---|
| models | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It adds '[WRITE][risk=medium]' indicating a write operation with risk level, and explains empty list behavior. However, it does not disclose if the replace is atomic, requires permissions, or has immediate effect.
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 extremely concise: two lines with no wasted words. It front-loads the risk indication and directly states purpose, followed by a clear parameter definition.
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 tool with one parameter and no output schema, the description is largely complete. It covers parameter format, replace behavior, and empty list semantics. Minor gap: lack of contrast with set_model_denylist sibling.
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% (no description in schema), so description must compensate. It explains that models are 'Shell-glob patterns of permitted model names' with an example, adding significant meaning beyond the schema's array type.
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 'Replace' and the resource 'model allowlist', specifying glob patterns and the behavior for empty list (allow-all). This distinguishes it from siblings like set_model_denylist.
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 setting allowed models via glob patterns, but does not explicitly contrast with siblings like set_model_denylist or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Replace the model denylist (deny patterns always win).
Args: models: Shell-glob patterns of forbidden model names.
| Name | Required | Description | Default |
|---|---|---|---|
| models | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It reveals the tool is a WRITE operation with medium risk, and that the denylist replaces the entire list with patterns that always win. However, it does not disclose persistence or effect on currently running models.
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 extremely concise: a single line with the WRITE tag and purpose, followed by a parameter description. Every word adds value, with no redundancy. It is front-loaded with the most important 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 low complexity (one parameter, no output schema), the description covers the tool's core purpose and behavior adequately. It explains the replacement action and pattern syntax, though it could hint at return values or confirm whether the change is applied globally or session-based.
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 input schema has 0% description coverage, so the description entirely compensates by explaining that 'models' are 'Shell-glob patterns of forbidden model names', providing essential semantics beyond the schema's minimal definition.
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 replaces the model denylist, using specific verb ('Replace') and resource ('model denylist'), and distinguishes it from sibling tools like set_model_allowlist by noting 'deny patterns always win'.
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 that the denylist overrides the allowlist ('always win'), but does not explicitly state when to use this tool over others (e.g., set_model_allowlist) or mention prerequisites or consequences of replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so its real risk tier is recorded there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an _undo_id in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| dry_run | No | ||
| undo_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses risk level (medium), the mechanism of dispatching an inverse tool through its own governed tool, the one-time nature of token usage, and the dry_run preview behavior. Comprehensive for a write operation with no annotations.
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?
Concise and well-structured: a header with risk tag, a paragraph on behavior, then a list of parameters. Every sentence adds value with no 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?
Covers purpose, parameters, risk, constraints, and preview mode. Adequate for a meta-tool with no output schema; only minor missing details like error handling, but overall 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?
Despite 0% schema coverage, the description adds an 'Args' section explaining each parameter's meaning and source (e.g., undo_id from undo_list). Fully compensates for missing schema descriptions.
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 'Apply a recorded undo by dispatching its inverse tool' with a specific verb and resource. It distinguishes from siblings like undo_list by focusing on application rather than listing.
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 explicit guidance: undo_id should come from undo_list, dry_run to preview without executing, token can be applied once. Implies when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that undo_apply
would run, and a human note. Use the undoId with undo_apply.
Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}.
truncated is measured (one extra row is fetched), not guessed from a
length coincidence: when it is true there are MORE tokens than shown, so
re-run with a higher limit rather than reporting the list as complete.
Each entry carries effectVerified. False means the original write lost
its response, so the change it reverses is PROBABLE, not confirmed — check
the live state before applying, and do not report the result as a restore
of a state that may never have been reached.
Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the read-only nature via [READ] tag, explains the truncated measurement method (fetching one extra row), details effectVerified semantics and implications, and notes that target is unused. Comprehensive coverage beyond minimal requirements.
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?
Well-structured with clear sections: purpose, output format, behavioral notes, and parameter details. Every sentence adds value without redundancy. Front-loaded with the main purpose and key usage hint.
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 output schema, the description fully defines the return structure and edge cases (truncated, effectVerified). References sibling tool undo_apply and provides actionable guidance. No gaps identified.
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?
With 0% schema description coverage, the description fully compensates: explains limit default of 50 and cap of 500, and clarifies that target is unused but accepted for CLI uniformity. No ambiguity remains.
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 it lists recorded, not-yet-applied undo tokens in reverse chronological order. It distinguishes itself from sibling tools like undo_apply by specifying it is a read operation for inspecting available undo actions.
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?
Explicitly mentions using the undoId with undo_apply, advises re-running with higher limit when truncated, and cautions about effectVerified. Lacks explicit when-not-to-use guidance, but provides sufficient context for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[WRITE][risk=medium] Evict a model from VRAM (keep_alive:0).
Args: model: Model name to unload. target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description alone must disclose behavior. It states it's a write and risk level, but omits details like reversibility, impact on model availability, and side effects.
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 sentences plus args list; no fluff. Every sentence adds value. Front-loaded with risk tag.
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 two-parameter tool with no output schema, the description covers basic usage. However, lacks context on return value, error conditions, and undo integration (siblings include undo_list).
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 has 0% description coverage. The description explains 'model: Model name' and 'target: Ollama target name from config; omit for default.', adding meaning beyond type and default.
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 'Evict a model from VRAM (keep_alive:0).' This clearly defines the action (evict/unload) and resource (model), distinguishing it from siblings like remove_model (delete model) and pull_model (download).
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 marks the operation as a write with medium risk but does not explicitly contrast with alternatives (e.g., vs remove_model for deletion). Usage context is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Query the observed-usage log (route-through prompts + their findings).
Args: model: Filter by model name. risk_level: Filter by risk band (none/low/medium/high/critical). allowed: True = only allowed calls; False = only blocked. since: ISO start timestamp. limit: Max rows.
Returns {"events": [...], "count": N, "returned": N, "limit": L, "truncated": bool}. When truncated is true more prompts were observed
than were returned — raise the limit or narrow the filters. Never conclude
"no risky prompts were observed" from a truncated result.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| model | No | ||
| since | No | ||
| allowed | No | ||
| risk_level | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it returns a specific data structure with truncated flag, and warns about result interpretation. Since no annotations are provided, the description carries full burden. It could mention that it is a read-only operation with no side effects, but that is implied by '[READ]'.
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 (~11 lines) and well-structured: first line states purpose, then parameter list, then return structure with a critical usage warning. Every sentence adds value with no 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 query tool with 5 optional parameters and no output schema, the description fully specifies the return format and explains truncation behavior. It covers all necessary context for an AI agent to use the tool 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 explain parameters. It provides brief but meaningful descriptions for all 5 parameters (e.g., 'model: Filter by model name.', 'risk_level: Filter by risk band (none/low/medium/high/critical).'). Adds meaning beyond schema types and defaults.
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 starts with '[READ]' and clearly states it queries the observed-usage log for route-through prompts and their findings. Verb 'Query' and resource 'usage log' are specific, and the sibling tools list includes other operations like scan_prompt, so purpose 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?
Provides clear guidance on interpreting truncated results and warns against drawing conclusions from truncated data. However, it does not explicitly state when to use this tool versus alternatives like scan_prompt or anomaly_report.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[READ] Total VRAM used by loaded models; flag over-budget.
Args: budget_bytes: Optional VRAM budget; models over it are flagged. target: Ollama target name from config; omit for the default.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| budget_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Clearly states it reads VRAM and optionally flags over-budget models. Does not mention side effects, permissions, or rate limits, but for a read operation the behavior is adequately disclosed. The [READ] tag helps.
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?
Extremely concise: one sentence plus two arg lines. Every sentence adds value. Front-loaded with '[READ]' for quick scanning.
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?
No output schema, so description should explain return values. Implies output includes total VRAM and flagged models, but lacks format details. Does not mention edge cases like no models loaded or invalid target. Adequate for a simple query but not fully 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 coverage is 0%, so description must compensate. Describes budget_bytes as 'Optional VRAM budget; models over it are flagged' and target as 'Ollama target name from config; omit for the default.' Adds meaning beyond schema types but minimal detail.
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?
Starts with '[READ]' clearly indicating read operation. States specific verb+resource: 'Total VRAM used by loaded models; flag over-budget.' Distinguishes from siblings like running_models (lists models) and server_status (general status) by focusing on VRAM usage and budgeting.
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 explicit when-to-use or alternatives. The budget_bytes parameter hints at context (monitoring VRAM budgets), but no guidance on when to use this over other monitoring tools like server_status or running_models.
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. Dates show when Glama detected each change.
v0.10.0proxy_guidancev0.6.0anomaly_reportguarded_generatelist_modelsmodel_detailsmodel_provenanceobserve_chatpin_model_digestpolicy_viewpull_modelremove_modelrunning_modelsscan_promptserver_statusset_model_allowlistset_model_denylistundo_applyundo_listunload_modelusage_eventsvram_usageEach tool targets a distinct action or resource (e.g., listing models, pulling, scanning, policy). There is no overlap in functionality; descriptions clearly differentiate purposes.
All tools follow a consistent verb_noun pattern in snake_case (e.g., list_models, pull_model, set_model_allowlist). The naming is predictable and uniform across all 20 tools.
With 20 tools, the set covers model management, monitoring, policy, scanning, and undo operations. While the count is on the higher end, each tool serves a clear purpose and the complexity is justified by the domain.
The tool surface provides full lifecycle coverage: model CRUD (list, pull, remove), runtime state (running, VRAM), safety scanning, policy management, provenance verification, usage logging, and undo. No obvious gaps for an AI model guardian.
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AIops-tools/AI-Guardian'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
