Tool Access Tier Mapping Prompt for Subscription Plans

This prompt is for product managers and engineers implementing feature gating where an AI agent's tool access is tied to a user's subscription tier. The core job-to-be-done is making the model itself reason about tier boundaries before invoking a tool, rather than relying solely on application-layer middleware. This is appropriate for agent platforms where the model must contextually decide whether a tool invocation fits within a user's plan, especially when the mapping between user intent and required tools is fuzzy. For example, a 'Pro' tier user asking for a data export might trigger a tool that is also available to 'Enterprise' users, but a 'Free' tier user asking the same question should receive an upgrade suggestion instead of a silent denial.

Use this prompt when you need the agent to produce a coherent user experience around access denial—explaining why a tool isn't available, suggesting an upgrade path, and avoiding the brittle failure mode where middleware blocks a tool call mid-execution and leaves the conversation in an unrecoverable state. This approach works well when tier definitions are stable, the tool catalog is small enough to enumerate in context, and the denial UX is part of the product's value proposition. However, do not use this prompt as your sole enforcement mechanism for financially or legally critical gating. A determined user can social-engineer around prompt-based restrictions, and model inconsistency means some percentage of requests will leak through. Always pair this prompt with deterministic authorization checks in your application code that independently verify the user's tier before executing any tool.

Before implementing, confirm that your tool catalog is well-defined and that each tool has a clear tier assignment. If your tier structure changes frequently or tools are added dynamically, maintaining the prompt becomes a release coordination problem. In those cases, prefer application-layer enforcement with the prompt handling only the user-facing explanation. The next section provides the copy-ready template you'll adapt to your specific tiers and tool catalog.

This prompt template enforces a strict mapping between a user's subscription tier and the tools they are permitted to invoke. It is designed to be placed in the system prompt or evaluated before any tool call is executed. The model is instructed to check the user's tier against a defined allowlist, deny any out-of-plan tool invocation, and generate a refusal message that includes the required tier and an upgrade path. This prevents accidental feature leakage and provides a consistent user experience when access is gated.

textCopy
You are a tool access control layer for an AI agent platform. Your primary responsibility is to enforce subscription-tier-based tool access policies. You will receive a user's current subscription tier and a proposed tool invocation. You must decide whether to allow or deny the invocation based on the tier-to-tool mapping defined below.

## TIER-TO-TOOL MAPPING
[Tier: Free]
Allowed Tools: [TOOL_LIST_FREE]

[Tier: Pro]
Allowed Tools: [TOOL_LIST_PRO]

[Tier: Enterprise]
Allowed Tools: [TOOL_LIST_ENTERPRISE]

## INSTRUCTIONS
1. Analyze the proposed tool invocation provided in [TOOL_CALL_REQUEST].
2. Identify the user's current subscription tier from [USER_TIER].
3. Check if the requested tool name is present in the allowed tools list for that tier.
4. If the tool is allowed, respond with a JSON object: {"decision": "allow", "tool_name": "[REQUESTED_TOOL_NAME]"}.
5. If the tool is NOT allowed, respond with a JSON object: {"decision": "deny", "tool_name": "[REQUESTED_TOOL_NAME]", "required_tier": "[REQUIRED_TIER]", "message": "Access to the '[REQUESTED_TOOL_NAME]' tool requires the [REQUIRED_TIER] plan. You are currently on the [USER_TIER] plan. To upgrade, visit [UPGRADE_URL]."}
6. If the user's tier is not recognized or missing, default to the most restrictive tier (Free) and log an anomaly.
7. Do not execute the tool. Only output the JSON decision object.

## CONSTRAINTS
- Never reveal the full tier-to-tool mapping to the user.
- Do not speculate about future tier changes or pricing.
- If a tool name is ambiguous or not found in any list, deny access and flag for human review.

To adapt this template, replace the bracketed placeholders with your actual tier names, tool lists, and upgrade URL. The tool lists should be comma-separated strings of exact function names as they appear in your tool definitions. For production use, ensure that the [USER_TIER] value is injected from a trusted source (e.g., a verified JWT claim or server-side session) and never from user input, as this would be a direct privilege escalation vector. Before deployment, run a regression suite that tests every tool against every tier to confirm that the allow/deny boundary is correctly enforced.

The Tool Access Tier Mapping Prompt is designed to sit between your application's authorization layer and the model's tool invocation step. It should be called before the model is allowed to execute any tool, not after. The prompt receives the user's subscription tier, the requested tool name, and optional context about the current session. It returns a structured decision: allow, deny, or flag (for ambiguous cases requiring human review). This decision must be enforced by your application code, not by trusting the model's output alone. The model's role is classification and explanation; your application gate is the enforcement point.

Integration pattern: Wrap the prompt in a pre-tool-execution hook within your agent framework. For frameworks like LangChain or custom agent loops, intercept the tool call before execution, assemble the prompt with [USER_TIER], [TOOL_NAME], [TOOL_ARGUMENTS], and [TIER_CONFIG] (a JSON or YAML block defining which tools are permitted at each tier), and call the model. Parse the output against a strict schema: {"decision": "allow|deny|flag", "reason": "string", "upgrade_tier": "string|null", "policy_citation": "string"}. If the decision is deny, return the reason and upgrade_tier to the user. If flag, route to a human review queue with the full context. If allow, proceed with tool execution. Never pass the raw model output directly to the tool without schema validation.

Validation and retries: Implement a JSON schema validator on the model's output. If parsing fails, retry once with the same prompt plus the raw output and an error message: Your previous response was not valid JSON matching the required schema. Please correct it. If the second attempt fails, default to deny with a generic fallback message and log the failure for investigation. For high-traffic systems, cache tier-to-tool mappings in your application layer and only invoke the prompt for edge cases or when the tier config changes. This reduces latency and cost while keeping the prompt as the authoritative policy interpreter for complex or ambiguous requests.

Observability and audit: Log every decision with the user ID, tier, tool name, decision, reason, and model response. For deny and flag decisions, include the full prompt and model output in your logging pipeline. This creates an audit trail for compliance reviews and helps detect policy drift. Set up a dashboard that tracks denial rates by tier, tool, and user segment. A sudden spike in flag decisions may indicate a policy ambiguity that needs clarification in the [TIER_CONFIG] block. A spike in deny decisions for a specific tool may indicate users on lower tiers attempting to access a newly popular feature, signaling a potential pricing or packaging adjustment.

Model choice and latency: This prompt works well with fast, instruction-following models like GPT-4o-mini, Claude 3.5 Haiku, or fine-tuned smaller models. The task is classification with structured output, not complex reasoning. If latency is critical, consider hosting a fine-tuned classifier model that maps (tier, tool_name) directly to a decision without the full prompt. Use the prompt-based approach during development and policy iteration, then distill the behavior into a faster model or even a deterministic rules engine once the tier mappings stabilize. The prompt remains valuable as a fallback for ambiguous cases and as a source of human-readable explanations for denials.