Per-tool context enriches operation descriptions with curated snippets from a context directory. These snippets provide domain-specific hints such as field semantics, guardrails, and usage caveats. The goal is to improve guidance for LLMs and UI consumers without altering schemas or business logic.

Per-tool context enrichment

When enabled, per-tool context appends a Context block to the operation description. The block can preserve newlines or appear as a single line.

For example,
  • In newline-preserving mode, the context block appears as:
    Context:
Allowed status values: NEW | RUNNING | COMPLETE
Max page size: 100
… (truncated)
  • In single-line mode, the context block appears as:
    Context: Allowed status values: NEW | RUNNING | COMPLETE … (truncated)

Activate per-tool context

The following steps describe how to activate per-tool context:
  1. Set the feature gate openapi_visibility.per_tool_context_enabled to true. By default it is set to disabled.
  2. Resolve the context directory in the following order:
    1. The context directory uses the explicit value of the openapi_visibility.context_dir property if it is provided.
    2. If the property is not provided, it checks for a ./context directory relative to the current working directory.
    3. If neither of the above exists, it falls back to the context/ directory located in the repository source tree.
  3. For each operation with an operationId, look for <operationId>.md and then <operationId>.txt in the context directory.
  4. Sort candidate files by descending priority and then by operationId. Truncate the list to per_tool_context_max_files if set.
  5. Append each selected file according to global defaults if not already present. Global context supports only global.md. Other filenames are ignored.

Append global context from global.md

If global.md exists in the resolved context directory, its content is appended to:
  • spec.info.description for a high-level overview with the help of the annotator.
  • Every operation description as a Global Context: block or line when context features are enabled.
The following table describes configuration tuning settings that control global context size and formatting behavior:
Setting Description
Size limit The openapi_visibility.global_context_char_limit property sets the size limit for global context. The default value is 1500 characters, and the maximum allowed is 2000 characters.
Formatting Formatting respects the settings defined in _index.json.defaults for newline preservation and truncation.
You can follow this guidance on recommended content that should be included in the global.md file when using the Global Context feature in OpenAPI visibility and context management:
  • Data freshness—State how often the inventory or data is updated.
  • Pagination—Provide limits and usage hints for pagination.
  • Rate limiting—Indicate throttling behavior for large queries.
The following example shows the recommended content in concise bullet points:
Data freshness: Inventory updated every 15 minutes.
Pagination: Top max 500; use Skip for offsets.
Rate limiting: Burst queries >10k items may throttle.
Note: Lengthy procedural guides, secrets, or large tables.

Control formatting with _index.json

The _index.json file inside the context directory provides optional global formatting controls and operation priorities. For example:
{
  "defaults": {
    "priority": 0,
    "preserve_newlines": false,
    "max_lines": 8,
    "char_limit": 400
  },
  "operations": {
    "GetItems": { "priority": 80 },
    "SearchItems": { "priority": 60 }
  }
}
Note:
  • Only priority is honored per operation. Legacy keys such as preserve_newlines, max_lines, and char_limit are ignored.
  • Defaults apply globally to all operations.

Apply formatting and truncation rules

You can adjust how context snippets are formatted and truncated by changing the global defaults in _index.json.defaults. The following table explains each setting:
Setting Data type Description
preserve_newlines Boolean If false, the context is collapsed into a single line. If true, original lines are preserved up to the value of max_lines.
max_lines Integer Specifies the maximum number of lines retained when preserve_newlines is true. If the limit exceeds, the system adds … (truncated) to indicate truncation.
char_limit Integer Defines the maximum number of characters before line splitting occurs. The hard upper bound is 2000 characters. Truncation respects newline boundaries whenever possible to avoid mid-line cuts and appeands … (truncated).

Apply priority and limits

Operations are sorted by priority. If per_tool_context_max_files is set, only the first N operations are enriched. This allows staged rollouts, such as highlighting the top 10 most-used operations.

Ensure idempotency and avoid collisions

When enriching API specifications with per-tool context, the system must ensure that the process does not create duplicate entries or introduce inconsistencies.

Idempotency ensures that running the enrichment multiple times produces the same result without duplication. If the enrichment process is executed more than once, the system checks for an identical formatted block in the operation description. If the block already exists, it is skipped. This ensures that repeated runs do not add duplicate context.

Collision avoidance prevents near-duplicate content from being added when similar information already exists in the operation description. Before adding new context, the system compares the first line of the raw file (up to 40 characters) with the existing description. If this snippet already appears, enrichment is skipped. This prevents adding content that is too similar to manually documented details.

Review logging behavior during enrichment

When the enrichment process runs, the system generates log messages to indicate actions taken:
  • If per-tool context is successfully added, the log message is:
    Visibility: added per-tool context to X operations (dir=...)
    This message confirms the number of operations enriched and the directory used.
  • If unsupported per-operation keys are removed, the log message is:
    Visibility: stripped N unsupported per-operation context keys

    This message indicates how many invalid keys were detected and stripped during processing.

Avoid common pitfalls when using per-tool context

The following table lists common pitfalls, what happens when they occur, and how to resolve them:
Pitfall Symptom Fix
Forgetting to enable per_tool_context_enabled No context lines appear in the operation descriptions Set the per_tool_context_enabled flag to true in the configuration.
Using per-operation formatting keys Formatting keys are silently ignored Move all formatting settings to the defaults section in _index.json.
Large context files Context is aggressively truncated Refactor the content into concise bullet points to fit within limits.
Duplicate run of enrichment No duplication occurs (expected behavior) This is working as intended. No action is required.
Missing operationId in operations No context is injected Ensure that every operation in the specification includes an operationId.