Tool Permission Scope Description Prompt

Use this prompt when you need to document the exact access scope a tool requires so that an AI model can reason about permission boundaries before calling it. The primary job-to-be-done is producing a machine-readable and human-auditable scope annotation that answers: what resources does this tool touch, what operations does it perform, and what is the least-privilege profile that still allows correct execution. The ideal user is a security engineer, platform architect, or authorization designer who is integrating AI tool-calling into a production system where tools have real side effects—reading customer data, mutating records, sending communications, or accessing internal services. Without explicit scope documentation, models cannot reliably decide whether a requested tool call exceeds the user's or session's granted permissions, which leads to either over-permissioning or broken workflows.

This prompt is not a replacement for your authorization enforcement layer. It produces scope annotations that inform model reasoning and pre-execution guardrails, but the actual enforcement must happen in your gateway or policy engine. Do not use this prompt when you need a full access-control policy language (e.g., Rego, Cedar) or when you are designing the enforcement mechanism itself. It is also inappropriate for tools that have no security-relevant side effects—if a tool only performs local computation with no external resource access, a permission scope description adds noise rather than safety. The prompt works best when you have a concrete tool schema already defined, including its parameters, side effects, and target resources, and you need the model to produce a structured scope annotation that can be compared against a user's granted scopes at runtime.

Before using this prompt, ensure you have the tool's full function definition, including all parameters, the resources it accesses (e.g., database tables, API endpoints, file paths), and a clear statement of whether it reads, writes, or administers those resources. The output should be a structured scope object—typically a JSON document with resource identifiers, operation types, and optional conditions—that your authorization middleware can parse and compare against session tokens. After generating the scope description, you must test it with eval cases that verify the model correctly refuses to call the tool when a requested scope exceeds the granted set, and correctly proceeds when scopes match. The next step is wiring this annotation into your tool registry so every tool call is preceded by a scope check that uses the model's own reasoning about permission boundaries.

This prompt takes a tool's full definition—its name, description, parameters, and side-effect documentation—and produces a structured permission scope. The output is designed to be consumed by an authorization system or a model reasoning about whether a requested action falls within granted boundaries. Use this template when you need to define, audit, or standardize the access scope for a single tool before it is registered in a production system.

textCopy
You are a security engineer specializing in least-privilege access control for AI tool-use systems. Your task is to analyze the provided tool definition and produce a structured permission scope annotation.

## INPUT

[TOOL_DEFINITION]

## INSTRUCTIONS

1. Identify every resource, operation, and data category the tool can access.
2. Classify the tool's side effects as READ_ONLY, WRITE, or ADMIN.
3. Define a permission scope string that precisely captures the minimum access required for the tool to function.
4. List any sensitive data categories the tool could expose (PII, secrets, financial data, etc.).
5. Recommend a least-privilege policy: what should be explicitly denied even if the tool could technically access it.
6. Flag any parameters that could be used to escalate access or bypass intended scopes.

## OUTPUT_SCHEMA

Return a valid JSON object with this exact structure:
{
  "tool_name": "string",
  "side_effect_classification": "READ_ONLY | WRITE | ADMIN",
  "permission_scope": "string (e.g., 'read:documents:project_alpha')",
  "accessed_resources": ["string"],
  "sensitive_data_exposure": ["string"],
  "least_privilege_deny_rules": ["string"],
  "escalation_risk_parameters": ["string"],
  "requires_human_approval": true | false,
  "approval_justification": "string (required if requires_human_approval is true)"
}

## CONSTRAINTS

- Do not invent resources or data categories not present in the tool definition.
- If the tool definition lacks side-effect documentation, classify it as WRITE by default and flag this assumption.
- The permission_scope string must follow the format: <action>:<resource>:<scope_qualifier>.
- If the tool can access multiple resource types, list each as a separate scope string in accessed_resources.
- Be conservative: when in doubt, recommend human approval.

To adapt this prompt, replace the [TOOL_DEFINITION] placeholder with the complete JSON or YAML definition of a single tool, including its function name, description, parameter schema, and any existing side-effect or auth annotations. If your tool catalog uses a different permission scope format, update the permission_scope field description and the format constraint accordingly. For high-security environments, add a [RISK_LEVEL] placeholder and adjust the requires_human_approval logic to trigger at lower thresholds. Always validate the output JSON against the schema before storing it in an authorization registry, and run a refusal eval to confirm the model correctly denies execution when a requested tool exceeds its granted scope.

The Tool Permission Scope Description Prompt is designed to be called programmatically as part of a tool registration or change-review workflow, not as a one-off chat interaction. In a typical implementation, every time a developer submits a new tool schema or modifies an existing one, the system sends the tool definition (name, description, parameters, side-effect annotations) to the model along with this prompt. The model returns a structured scope annotation and a least-privilege recommendation. The output is then stored alongside the tool definition in a tool registry or configuration store, where it can be consumed by an authorization engine at runtime. This prompt is a pre-execution design-time control, not a runtime enforcement mechanism.

To integrate this into an application, wrap the prompt in a service that accepts a tool definition object and returns a validated scope annotation. The service should enforce a strict output schema (e.g., required_scopes, optional_scopes, justification, least_privilege_recommendation, risk_notes) and validate the response before persisting it. If the model returns malformed JSON, missing required fields, or scopes that don't match your organization's predefined scope catalog, the service should retry with a repair prompt or escalate for human review. Log every invocation—including the input tool definition, the model's raw output, and the final validated annotation—so that security auditors can trace why a particular tool was granted a given scope. For high-risk tools (those with write, admin, or user_data_access side effects), require a human security engineer to approve the annotation before the tool is registered. This can be implemented as a simple review queue in your tool registry UI.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) because the task requires precise reasoning about security boundaries and consistent JSON generation. Avoid smaller or older models that may hallucinate scope names or fail to distinguish between read and write operations. If your organization uses a custom scope taxonomy, include it as part of the [CONTEXT] placeholder in the prompt template. Do not rely on the model to invent scope names; constrain it to your known set. The eval harness for this prompt should include test cases where the model is given a tool that exceeds a hypothetical granted scope and must correctly recommend refusal or scope reduction. Measure precision and recall of scope assignments against a golden set of human-annotated tools, and track the rate of human overrides in the review queue as a leading indicator of prompt drift.

Finally, connect this prompt's output to your runtime authorization system. When an agent or application attempts to call a tool, the authorization layer should check the tool's registered scopes against the caller's granted permissions. If the tool's required_scopes are not met, the call is blocked before execution. This prompt does not enforce permissions—it documents them. The enforcement must happen in application code. A common failure mode is treating the model's scope annotation as authoritative without human review or runtime enforcement, which creates a false sense of security. The prompt is a documentation accelerator, not a security control. Always pair it with a hard authorization gate.