Skip to main content
Glama
Guardian by Odingard

Guardian by Odingard

Run a tool through Guardian

guardian_invoke_tool
Destructive

Run a registered tool through Guardian's rules so it is allowed, held for human approval, or denied before execution. Enforces policy on every call.

Instructions

Run a tool registered on a Guardian connection, instead of calling it directly. Guardian's rules decide ALLOW, ASK or DENY before anything runs. ALLOW runs the tool at once (it can change the target system) and returns the decision, requestId and execution record. ASK runs nothing and returns a requestId: wait for the person to approve it in Guardian, then call guardian_claim. DENY, or Guardian unreachable (reasonCode SERVICE_UNAVAILABLE), runs nothing; each call is a new request, so after an unknown outcome check guardian_record before calling again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "toolName": "<toolName>"
    },
    "name": "guardian_invoke_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
purposeNoShort plain-language reason for this action, recorded with the request. At most 1,024 characters.
toolNameYesName of the tool as registered on the Guardian connection, for example "send_email". Lowercase letters and digits joined by . _ or -, at most 64 characters.
argumentsNoThe tool's own input, as the JSON object the tool takes (at most 16,384 bytes of JSON, UTF-8). Guardian decides on these exact arguments, and an approved call runs with them unchanged. Defaults to {}.
connectionIdNoId of the Guardian connection the tool is registered on (starts with pcn_), as shown in the Guardian console. Optional when the server sets GUARDIAN_CONNECTION_ID; required otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.5.3
    • changedInput schema / properties / arguments / description
      Previous value: -"Arguments the tool would run with."New value: +"The tool's own input, as the JSON object the tool takes (at most 16,384 bytes of JSON, UTF-8). Guardian decides on these exact arguments, and an approved call runs with them unchanged. Defaults to {}."
    • changedInput schema / properties / connectionId / description
      Previous value: -"Tool connection id. Defaults to GUARDIAN_CONNECTION_ID."New value: +"Id of the Guardian connection the tool is registered on (starts with pcn_), as shown in the Guardian console. Optional when the server sets GUARDIAN_CONNECTION_ID; required otherwise."
    • addedInput schema / properties / connectionId / pattern
      Added value: +"^pcn_[A-Za-z0-9][A-Za-z0-9_-]{7,119}$"
    • changedInput schema / properties / purpose / description
      Previous value: -"Human-readable reason for this action."New value: +"Short plain-language reason for this action, recorded with the request. At most 1,024 characters."
    • addedInput schema / properties / purpose / maxLength
      Added value: +1024
    • changedInput schema / properties / toolName / description
      Previous value: -"Registered tool name."New value: +"Name of the tool as registered on the Guardian connection, for example \"send_email\". Lowercase letters and digits joined by . _ or -, at most 64 characters."
    • addedInput schema / properties / toolName / maxLength
      Added value: +64
    • addedInput schema / properties / toolName / minLength
      Added value: +1
    • addedInput schema / properties / toolName / pattern
      Added value: +"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$"
  2. First observedv0.5.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say destructive/openWorld/not-idempotent; the description supplies what actually happens: rules gate execution before anything runs, ALLOW mutates the target system and returns decision, requestId and execution record, ASK runs nothing. It also discloses a failure reason code (SERVICE_UNAVAILABLE) and non-idempotency implications ('each call is a new request'), which annotations alone cannot convey.

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-loaded with the core purpose, then organized by decision branch in the order an agent will encounter them. Dense semicolon-chained sentences pack a lot of decision logic efficiently, though the ALLOW/ASK/DENY run-on could be split for faster scanning.

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

Completeness5/5

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

There is no output schema, so the description carries return-value burden and does so: decision, requestId and execution record on ALLOW, requestId-only on ASK. Failure modes, the unreachable-server case, and the recovery path via siblings are all covered for a destructive, open-world mediation tool.

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

Parameters3/5

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

Schema coverage is 100%, so all four parameters (purpose, toolName, arguments, connectionId) are already documented with formats and patterns. The description adds only that Guardian evaluates the exact arguments and that approved calls run with them unchanged; it does not explain purpose, connectionId resolution, or the 16KB argument bound beyond the schema.

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

Purpose5/5

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

States a specific verb and resource ('Run a tool registered on a Guardian connection') and immediately scopes it against the default behavior ('instead of calling it directly'). The mediation layer (Guardian rules) is named, so an agent can tell this apart from invoking a tool directly.

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

Usage Guidelines5/5

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

Gives explicit branching guidance per outcome: ALLOW means it already ran, ASK means call guardian_claim after human approval, DENY/SERVICE_UNAVAILABLE means nothing ran. It also warns that each call is a new request and points to guardian_record after an unknown outcome, so both alternatives and their triggering conditions are named.

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