Define goals and guiding principles

Visibility enrichment is designed to:

• Provide small, deterministic filter examples so that a user interface (UI) can quickly suggest how to use complex filtering.
• Supply non-intrusive parameter examples for existing query or path parameters. These examples never create new parameters, never overwrite explicit examples, and skip sensitive names.
• Inject lightweight per-tool context snippets from a local directory. Ordering is controlled by priority and capped through configuration.

The following design principles define how visibility enrichment and context management features operate to ensure consistency and predictability:

• Read-only—Enrich specification descriptions only. Do not modify schemas except to add examples.
• Deterministic—The same specification and context directory always produce identical output.
• Safe defaults—Features are disabled unless explicitly enabled. Parameter examples are added only when requested.
• Size-bounded—Apply character and line truncation to prevent oversized context from leaking into prompt windows.

The following table summarizes important configuration properties for OpenAPI visibility and context management and explains their purpose:

Property	Purpose	Default or guidance
add_filter_examples	Add consolidated Filter Examples: (or Filter:) and sets an example on an existing filter parameter.	Disabled unless enabled. Uses first server URL and first 8 fields (maximum 3 predicates).
add_param_examples	Populates examples for existing query or path parameters. Skips sensitive names.	Disabled unless enabled. Non-destructive.
per_tool_context_enabled	Enables context injection from <operationId>.md or .txt files.	Disabled by default. Opt-in feature.
per_tool_context_char_limit	Sets maximum characters per per-tool snippet.	If not set, the internal default is 10000 characters, but it is capped at 2000 characters. For clarity and predictable behavior, set the value explicitly to 2000 or a lower number.
per_tool_context_max_files	Limits number of operations receiving context after priority sort.	Unlimited if unset or less than or equal to zero.
global_context_char_limit	Sets maximum characters pulled from global.md before distribution to all operations.	Default 10000. Recommended range is 3000–6000 for clarity.
context_dir	The directory is used to read global.md, per-tool files, and _index.json.	The system automatically detects the directory in the following order: An explicitly specified path ./context repo/context/
Catalog tools	Provides runtime introspection utilities, such as list_all_tags, get_tool_schema, and get_filter_fields.	Scope-gated if exposing internal schemas.