Tool Deprecation Notice Generation Prompt

This prompt is designed for API platform teams and developer-tooling engineers who need to communicate tool deprecation to an AI model in a structured, machine-readable way. The core job is not to write a human-facing changelog, but to generate a model-facing deprecation schema that includes a sunset date, a replacement tool mapping, and migration guidance. The ideal user is an engineering lead or platform architect responsible for a growing catalog of tools where old endpoints, parameters, or entire functions must be retired without breaking existing AI workflows that depend on them.

Use this prompt when you are actively retiring or replacing a tool in a production AI system and you need the model to stop selecting the deprecated tool, redirect to a successor, or explain the deprecation to the end user. It requires you to provide the deprecated tool's name, the reason for deprecation, the sunset date, and the replacement tool definition if one exists. The prompt is most effective when integrated into a tool registration pipeline where deprecation notices are injected into the system prompt or tool catalog alongside active tools. Do not use this prompt for minor parameter changes that don't break compatibility, for tools that are simply being renamed without behavioral changes, or for human-facing API changelogs where the audience is a developer reading documentation rather than a model making a tool selection decision.

Before using this prompt, ensure you have a clear deprecation policy in place. The generated notice will include a structured schema, but the effectiveness depends on your model's ability to respect deprecation signals. In high-stakes environments—such as financial transactions, healthcare operations, or safety-critical systems—you must pair this prompt with a pre-execution guardrail that validates the model did not call a deprecated tool. The prompt alone is a signal, not an enforcement mechanism. If your system cannot tolerate any deprecated tool calls, implement a hard block at the API gateway or tool execution layer rather than relying solely on model adherence to the notice.

This prompt template is designed to produce a structured deprecation notice that a model can interpret and act upon. It takes the deprecated tool's name, its replacement, a sunset timeline, and a migration guide as inputs. The output is a JSON schema that can be injected into the system prompt or tool catalog, allowing the model to understand that a tool is no longer preferred and to route requests to the replacement. The template uses square-bracket placeholders for all required inputs, making it easy to integrate into an automated CI/CD pipeline for your API's tool definitions.

codeCopy
You are an AI platform engineer generating a machine-readable deprecation notice for a tool in a model's function catalog. Your output will be parsed by a downstream system and injected into the model's available tools list.

Generate a JSON object that follows this exact [OUTPUT_SCHEMA]. The notice must clearly signal deprecation, provide a migration path, and include a sunset date.

## Inputs
- **Deprecated Tool Name:** [DEPRECATED_TOOL_NAME]
- **Replacement Tool Name:** [REPLACEMENT_TOOL_NAME] (use null if no direct replacement)
- **Sunset Date (ISO 8601):** [SUNSET_DATE]
- **Deprecation Reason:** [DEPRECATION_REASON]
- **Migration Guide (plain text):** [MIGRATION_GUIDE]
- **Risk Level:** [RISK_LEVEL] (must be one of: low, medium, high, critical)

## Constraints
- [CONSTRAINTS]

## Output Schema
```json
{
  "deprecation_notice": {
    "deprecated_tool": "string",
    "replacement_tool": "string | null",
    "sunset_date": "string (ISO 8601)",
    "reason": "string",
    "migration_guide": "string",
    "risk_level": "low | medium | high | critical",
    "model_instruction": "A concise, imperative sentence telling the model what to do when this tool is requested. E.g., 'Do not call this tool. Route all requests to [REPLACEMENT_TOOL_NAME] instead.'"
  }
}

Examples

[EXAMPLES]

To adapt this template, replace each bracketed placeholder with concrete values from your API's change management system. The [CONSTRAINTS] placeholder is critical for high-risk deprecations; use it to inject rules like 'If the sunset date is within 7 days, the model_instruction must begin with URGENT.' The [EXAMPLES] placeholder should contain one or two few-shot examples of correct deprecation notices for your specific tool ecosystem. After generating the notice, always validate the output against the [OUTPUT_SCHEMA] using a JSON Schema validator before injecting it into any production model context. For critical-risk deprecations, require a human review step in your deployment pipeline to confirm the migration guide is accurate and the replacement tool is fully operational.

This prompt is designed to run as a batch job or CI step, not as a real-time user-facing call. The typical integration point is a tool registry update pipeline: when an API team marks a tool as deprecated in their source of truth (OpenAPI spec, internal catalog, protobuf definitions), a webhook or scheduled job triggers this prompt to generate the model-facing deprecation notice. The output is a structured JSON payload that gets injected into the tool schema's deprecation field or published to a tool-change feed that AI gateways consume. Do not wire this prompt directly into a chat interface or agent loop—it produces infrastructure metadata, not conversational responses.

Validation and retry logic is critical because a malformed deprecation notice silently breaks model tool selection. After the prompt returns, validate the output against a strict JSON Schema that checks: deprecated is a boolean set to true, deprecation_date is an ISO 8601 date in the future, sunset_date is present and after deprecation_date, replacement_tool is either null or a valid tool identifier from your registry, and migration_notes is a non-empty string. If validation fails, retry once with the validation errors appended to the [CONSTRAINTS] block. If the second attempt also fails, route to a human reviewer via a ticket or Slack notification—never auto-merge a broken deprecation notice into production tool schemas. Log every generation attempt with the model version, prompt hash, input tool name, and validation result for auditability.

Model choice matters for consistency. Use a model with strong JSON Schema adherence (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set response_format to json_schema with the output schema provided inline. Avoid smaller or older models that may hallucinate dates, invent replacement tools, or omit required fields. If your tool registry already has a canonical deprecation policy (e.g., '90-day notice before sunset'), inject that policy into the [CONSTRAINTS] placeholder rather than relying on the model to infer it. For high-volume tool catalogs, consider batching multiple deprecation requests into a single prompt call with an array input to reduce latency and cost, but validate each array element independently.

Human review is required before the generated notice goes live if the tool being deprecated has production traffic, handles write operations, or is used by external customers. The review gate should present the generated deprecation notice alongside the tool's current usage metrics and a diff of the proposed schema change. The reviewer confirms three things: the sunset date aligns with the API team's communicated timeline, the replacement tool mapping is correct and the replacement tool actually exists, and the migration notes are accurate enough for a model to guide users to the right alternative. After approval, the notice is merged into the tool schema and the change is broadcast to all AI gateways that consume the tool catalog. Rejections should loop back to the API team with the reviewer's notes, not to the prompt—the prompt generates the draft, it doesn't decide policy.