Skip to main content
Glama
ShellFrameAI

AgentSecure Community

Official
by ShellFrameAI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

agentsecure.request_approval

Create a local pending approval record when a Mesh policy hint needs human review, returning an approval ID and pending status; decisions happen outside these MCP tools.

Instructions

Create a local pending approval record when a Mesh policy hint requires human review. Returns an approval object with approval_id, status=pending, requested_by, action, resource, required_approver, and timestamps; reason is redacted with a summary/hash. Writes local state and audit but does not send a message, notify a human, execute the action, or change policy. Repeated calls create separate requests. Use agentsecure.get_approval_status with the returned ID; approval decisions are made outside these MCP tools. An approved record does not automatically unblock policy. Example: {"requested_by": "frontend-agent", "action": "deploy_preview", "reason": "Please review the preview deployment."}.

Input Schema

NameRequiredDescriptionDefault
actionYesNon-empty proposed action label, e.g. deploy_preview; use the same action supplied to get_policy_hint. Records intent only and does not execute it.
reasonYesJustification to summarize/hash. Stored reason is [redacted], but up to 120 characters can remain in a heuristic summary. Do not include secrets.
resourceNoOptional resource metadata; defaults to {}. Stored/returned fields are limited to action, environment, id, path, provider, repo, team, and type. Use non-secret scalar values or lists; other keys and top-level object-valued fields are dropped; list items are converted to scalars, and strings are truncated/redacted. Example: {"type": "code_file", "path": "src/app.py"}. For policy checks, the entire supplied object is examined for sensitive-action markers.
requested_byYesNon-empty Mesh agent ID, e.g. backend-agent. Pass this session's AGENTSECURE_AGENT_ID value when set; it is not read automatically. IDs are caller-supplied local labels, not authentication credentials.
required_approverNoOptional approver metadata, e.g. {"type": "team", "id": "platform"}. Omitted/empty selects resource.team, then security team for a case-sensitive action containing security/secret, else human local-owner. Stored as supplied; use only non-secret labels. Does not authenticate an approver.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / action / description
      Added value: +"Non-empty proposed action label, e.g. deploy_preview; use the same action supplied to get_policy_hint. Records intent only and does not execute it."
    • addedInput schema / properties / reason / description
      Added value: +"Justification to summarize/hash. Stored reason is [redacted], but up to 120 characters can remain in a heuristic summary. Do not include secrets."
    • addedInput schema / properties / requested_by / description
      Added value: +"Non-empty Mesh agent ID, e.g. backend-agent. Pass this session's AGENTSECURE_AGENT_ID value when set; it is not read automatically. IDs are caller-supplied local labels, not authentication credentials."
    • addedInput schema / properties / required_approver / description
      Added value: +"Optional approver metadata, e.g. {\"type\": \"team\", \"id\": \"platform\"}. Omitted/empty selects resource.team, then security team for a case-sensitive action containing security/secret, else human local-owner. Stored as supplied; use only non-secret labels. Does not authenticate an approver."
    • addedInput schema / properties / resource / description
      Added value: +"Optional resource metadata; defaults to {}. Stored/returned fields are limited to action, environment, id, path, provider, repo, team, and type. Use non-secret scalar values or lists; other keys and top-level object-valued fields are dropped; list items are converted to scalars, and strings are truncated/redacted. Example: {\"type\": \"code_file\", \"path\": \"src/app.py\"}. For policy checks, the entire supplied object is examined for sensitive-action markers."
  2. First observed

TDQS

A4.6/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 burden and does well: it discloses local state and audit writes, redaction of reason into a summary/hash, that repeated calls create separate requests, and that an approved record does not unblock policy. It stops short of stating permissions or concurrency/idempotency guarantees for the audit write, which keeps it from a 5.

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 purpose and scoping negatives, and dense with no filler sentences. It is a long single paragraph for a 5-parameter mutation, though each clause carries distinct information; light structure (bullets or a short return-value sentence) would improve scanability.

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?

No output schema exists, yet the description enumerates returned fields (approval_id, status, timestamps, etc.), describes side effects, redaction, and the downstream decision workflow. Nothing needed to invoke or interpret the call is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes further by supplying a concrete example call and tying the action label to the one supplied to get_policy_hint, plus noting requested_by should come from AGENTSECURE_AGENT_ID and is a caller-supplied label, not a credential.

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?

Opens with a specific verb and resource: 'Create a local pending approval record when a Mesh policy hint requires human review.' It also names the return object shape and distinguishes itself from siblings by stating it does not execute, notify, or change policy, and routes to get_approval_status.

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 an explicit trigger (a policy hint requiring human review), explicit non-capabilities (no messaging, no notification, no execution, no policy change), the follow-up tool to use (agentsecure.get_approval_status with the returned ID), and the exclusion that decisions happen outside these MCP tools. It even warns that approval does not auto-unblock policy.

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

This server cannot be deployed

Other Tools