Tool-Call Observability Configuration Prompt

This prompt is for platform engineers and AI governance teams who need to move beyond ad-hoc logging and define a strict, machine-readable observability policy for every tool call an AI assistant makes. The job-to-be-done is generating a configuration object—typically JSON or YAML—that a production harness can enforce at runtime. This object specifies exactly which tool invocations must be logged, what arguments and responses to capture, how to handle authorization checks, and what error states to record. You should use this prompt when you are integrating an LLM into a system where every tool interaction must be auditable for debugging, security review, or compliance. The ideal user has a clear map of their available tools, their authorization boundaries, and the specific audit requirements they must satisfy.

Do not use this prompt for casual logging or simple debugging print statements. It assumes a production harness that will consume the generated policy and enforce it at the execution layer—for example, a middleware proxy that intercepts tool calls, validates them against the policy, and writes structured audit events to a logging backend. The prompt requires you to provide a complete tool manifest, including each tool's name, description, parameters, and authorization level. Without this context, the generated policy will be generic and unenforceable. You should also provide your observability requirements, such as which events are mandatory, what PII redaction rules apply, and what retention or compliance standards you must meet. If you cannot provide a concrete tool manifest and specific audit requirements, you are not ready for this prompt.

This prompt is also not a substitute for a full security review or a compliance certification. It generates a policy that your system must enforce; it does not itself enforce anything. The output is a configuration artifact that should be reviewed by a human before deployment, especially in regulated environments. After generating the policy, your next step should be to validate it against your actual tool execution layer, write integration tests that simulate both authorized and unauthorized tool calls, and verify that the generated audit records meet your downstream query and review needs. If you skip this validation, you risk a policy that looks complete on paper but silently misses critical events in production.

This prompt template defines a tool-call observability policy that you can paste directly into your system prompt or a dedicated policy-generation step. It instructs the assistant to log every tool invocation with argument capture, response recording, authorization checks, and error documentation. The template uses square-bracket placeholders so you can adapt it to your specific tool catalog, data access policies, and compliance requirements without rewriting the structural logic.

textCopy
You are an assistant with access to external tools. You must log every tool invocation according to the Tool Observability Policy below. Never skip logging, even if a tool call fails or is blocked.

## TOOL OBSERVABILITY POLICY

For every tool call you make or attempt, you MUST produce a structured log entry containing these fields:
- `tool_name`: The exact name of the tool invoked.
- `call_timestamp`: ISO 8601 timestamp of when the call was initiated.
- `arguments_passed`: A complete copy of all arguments sent to the tool. If an argument contains sensitive data classified as [SENSITIVE_DATA_CLASSES], redact the value and replace it with `[REDACTED]` while preserving the argument name.
- `authorization_check`: Before calling the tool, verify that the call is permitted under [TOOL_AUTHORIZATION_POLICY]. Record the result as `ALLOWED`, `DENIED`, or `CONDITIONAL`.
- `authorization_reason`: If `DENIED` or `CONDITIONAL`, cite the specific policy rule from [TOOL_AUTHORIZATION_POLICY] that applies.
- `response_received`: The full response from the tool, or `null` if no response was received. Apply the same redaction rules as for arguments.
- `error_encountered`: If the tool call failed, record the error type, message, and any error code. Otherwise `null`.
- `data_access_boundary_crossed`: `true` if the tool call accessed or returned data from [RESTRICTED_DATA_DOMAINS], otherwise `false`.
- `user_confirmation_required`: `true` if [CONFIRMATION_REQUIRED_TOOLS] includes this tool and confirmation was obtained, otherwise `false`.
- `confirmation_evidence`: If confirmation was required, record the confirmation ID or user acknowledgment. Otherwise `null`.

## LOGGING RULES
1. Produce the log entry immediately after the tool call completes or fails.
2. If a tool call is blocked by authorization policy, log the attempt with `DENIED` status and do not proceed.
3. If you are uncertain whether a tool call crosses a data access boundary, log `data_access_boundary_crossed` as `true` and note the uncertainty.
4. Never log raw credentials, tokens, or secrets. These must always be redacted.
5. If [AUDIT_RETENTION_REQUIREMENT] specifies a retention period, include a `retention_until` field with the calculated date.

## OUTPUT FORMAT
Return the log entry as a valid JSON object conforming to this schema:
[OUTPUT_SCHEMA]

## EXAMPLES
[EXAMPLES]

## CONSTRAINTS
[CONSTRAINTS]

To adapt this template, replace each square-bracket placeholder with your actual policies and schemas. [TOOL_AUTHORIZATION_POLICY] should contain the specific rules governing which tools can be called under what conditions—for example, 'Read-only tools may be called without confirmation; write tools require user approval.' [SENSITIVE_DATA_CLASSES] should list your data classification labels such as PII, PHI, credentials, or internal-secret. [RESTRICTED_DATA_DOMAINS] defines which data domains trigger boundary-crossing flags, such as customer_financial_data or employee_records. [CONFIRMATION_REQUIRED_TOOLS] enumerates the tools that need explicit user approval before execution. [OUTPUT_SCHEMA] should be a strict JSON schema definition that your application layer can validate. [EXAMPLES] should include at least one allowed call, one denied call, one error scenario, and one redaction example. [CONSTRAINTS] should specify any additional rules such as rate limits, concurrency restrictions, or environment-specific logging requirements. After adapting the template, run it through your eval harness against golden test cases that include authorized calls, unauthorized attempts, error conditions, and boundary-crossing scenarios. If your use case involves regulated data, ensure a human reviews the first batch of production logs before enabling autonomous operation.

This prompt is not a one-shot generator. It is a policy compiler that should run inside your CI/CD pipeline or AI gateway configuration step whenever tool schemas, data access policies, or authorization boundaries change. The output is a structured observability policy that your agent harness reads at runtime to decide what to log, how to redact arguments, and when to emit audit events. Do not paste this prompt into a chat window and expect a production-ready policy. It belongs in a deterministic pipeline step with validation, diff review, and human sign-off before deployment.

Wire the prompt into a policy generation service that triggers on changes to your tool manifest or OpenAPI spec. The service should: (1) load the current tool definitions, authorization matrix, and data classification labels into [TOOL_DEFINITIONS], [AUTHORIZATION_MATRIX], and [DATA_CLASSIFICATION_POLICY]; (2) invoke the model with response_format set to the JSON schema defined in the output contract; (3) run a structural validator that checks every required field (loggable_events, argument_capture_rules, redaction_patterns, error_recording_policy) is present and well-formed; (4) run a coverage validator that confirms every tool in the manifest has a corresponding observability rule; (5) diff the new policy against the previous version and flag any removed logging rules or relaxed redaction patterns for human review. Use a model with strong JSON mode and low temperature (0.1–0.2). GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro all work. Avoid small open-weight models here—schema precision and authorization reasoning matter too much.

At runtime, your agent harness loads the generated policy and instruments every tool-call boundary. Before invoking a tool, check the policy for argument_capture_rules: if the rule says capture: true, serialize the arguments; if redact_fields is specified, apply the redaction patterns before logging. After the tool returns, check response_logging—capture the response body only if the policy permits it, and apply the same redaction rules. For authorization violations, the harness should log the authorization_check fields (principal, permission, resource, decision) and emit a structured audit event. Never log raw tool responses before redaction. The policy is your allowlist. If a tool call doesn't match any rule, the harness should refuse to execute it and log an unmapped_tool_call error event. This is a fail-closed design.

Testing this system requires three layers. Unit tests validate the policy generator output against known tool manifests—feed it a manifest with a tool that reads PII and confirm the output policy requires argument redaction. Integration tests run the harness with a sample policy and verify that tool calls produce correctly shaped log events, redacted fields are absent, and authorization violations trigger the right audit records. Adversarial tests feed the policy generator edge cases: tools with overlapping permission boundaries, tools that call other tools, tools with dynamic argument schemas. The policy must handle these without dropping coverage. If the generated policy fails any test, block the deployment and escalate to a human reviewer. This is not a prompt you ship without gates.

Common failure modes to instrument for: (1) schema drift—a new tool is added to the manifest but the policy generator hasn't run, so the harness rejects all calls to it; (2) redaction leakage—a tool response contains PII in an unexpected field not covered by the redaction patterns, and the policy logs it raw; (3) over-logging—the policy captures full request/response bodies for high-volume tools, causing storage cost explosions; (4) authorization blind spots—the authorization matrix doesn't cover a new permission model, and the policy silently allows unauthorized tool calls. Monitor for each of these in production. Set alerts on unmapped_tool_call events, redaction pattern match failures, and sudden spikes in log volume per tool.

The generated policy is a living artifact. Store it in version control alongside your tool manifests. Every change to tool definitions, data classifications, or authorization rules must trigger a policy regeneration, a diff review, and a staged rollout. Treat the observability policy with the same rigor as your authentication and authorization code. If you skip the human review step on policy diffs, you will eventually log something you shouldn't, or miss something you needed for an audit. The prompt is the compiler; your review process is the type checker.