# How to Group Tools Using the OpenMontage Tool Registry Reporting Methods

> Discover the six OpenMontage Tool Registry reporting methods to group tools by capability provider tier and availability status for efficient orchestration logic and agent pre-flight menus.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The OpenMontage Tool Registry provides six distinct reporting methods—`capability_catalog()`, `provider_catalog()`, `tier_summary()`, `provider_menu()`, `provider_menu_summary()`, and `support_envelope()`—that group tools by capability, provider, tier, and availability status to drive orchestration logic and agent pre‑flight menus.**

The `ToolRegistry` class in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py) serves as the single source of truth for every tool available to the OpenMontage system. These Tool Registry reporting methods go beyond simple tool listing to offer sophisticated grouping capabilities that organize tools by functional family, external service provider, and operational readiness. By leveraging automatic discovery of concrete `BaseTool` subclasses, these helpers enable agents to build user‑facing menus and validate runtime configurations without manual registration overhead.

## Tool Registry Reporting Methods Overview

All reporting methods are defined in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py) and operate on the internal `_tools` dictionary populated by `ToolRegistry.discover()`. The `discover()` method walks the `tools` package via `pkgutil.walk_packages()` to register every concrete subclass of `BaseTool`, ensuring new tools immediately appear in all reports.

The reporting methods fall into three functional categories:

- **Catalog methods**: Group tools by static attributes (capability, provider)
- **Summary methods**: Aggregate tools by tier and availability status
- **Diagnostic methods**: Provide runtime‑ready views for orchestration and UI rendering

## Grouping Tools by Capability and Provider

### Capability Catalog

The `capability_catalog()` method iterates over the registered tools and groups `tool.get_info()` dictionaries by each tool’s `capability` attribute. Results are sorted by provider and name to produce a deterministic, browsable catalog.

```python
def capability_catalog(self) -> dict[str, list[dict[str, Any]]]:
    # Groups tools by capability (e.g., video_generation, tts)

    # Lines 12-20 in tools/tool_registry.py

```

This method returns a dictionary mapping capability strings to lists of tool metadata, making it ideal for building functional‑family menus where users browse by what a tool does rather than who provides it.

### Provider Catalog

The `provider_catalog()` method functions analogously to the capability catalog but groups tools by the `provider` attribute (e.g., `elevenlabs`, `fal`). This view is essential when verifying service coverage or isolating tools from a specific vendor.

```python
def provider_catalog(self) -> dict[str, list[dict[str, Any]]]:
    # Groups tools by provider name

    # Lines 22-30 in tools/tool_registry.py

```

## Analyzing Tool Tiers and Availability

### Tier Summary

The `tier_summary()` method aggregates tools by `ToolTier` enum values (`CORE`, `VOICE`, `ENHANCE`, etc.) and tallies counts per `ToolStatus`. This provides a high‑level health check of which tiers are fully operational versus degraded.

```python
def tier_summary(self) -> dict[str, dict[str, int]]:
    # Tallies available/unavailable tools per tier

    # Lines 32-47 in tools/tool_registry.py

```

The method returns a nested dictionary structure where each tier maps to status counts, enabling quick dashboard metrics without iterating the full registry.

### Provider Menu Structure

The `provider_menu()` method generates the pre‑flight structure that agents display to users. It first filters out selector tools (which aggregate rather than provide concrete functionality), then builds a nested dictionary keyed by capability. Each capability entry contains `available`, `unavailable`, `total`, and `configured` counts, allowing agents to indicate which integrations are ready for use and which require setup.

*Implementation note*: This method specifically splits tools into availability buckets to support the "green light / red light" UI patterns common in agent onboarding flows (lines 49‑66 in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py)).

## Runtime Diagnostics and Support Envelope

### Compact Menu Summary

The `provider_menu_summary()` method consumes the raw provider menu and extracts a compact, human‑readable roll‑up optimized for UI display. It returns three key elements:

- **Runtime support map**: Boolean indicators for configured runtimes
- **Capability list**: Configured versus total counts with provider availability breakdowns
- **Warnings**: Runtime‑specific issues such as missing npm packages

This method is the primary interface for agent quick‑start sequences that need to communicate configuration status without overwhelming users with raw tool lists.

### Full Support Envelope

The `support_envelope()` method provides the most comprehensive view, returning a dictionary keyed by individual tool name containing the complete `ToolInfo` payload. This includes status, cost metadata, dependencies, and contractual requirements.

```python
def support_envelope(self) -> dict[str, Any]:
    # Returns full contract info for every tool

    # Lines 98-104 in tools/tool_registry.py

```

Orchestrators use this low‑level data to validate tool selection constraints before execution, while the higher‑level grouping functions build user‑friendly abstractions on top of it.

## Practical Implementation Examples

The following patterns demonstrate how to initialize the registry and consume the Tool Registry reporting methods:

```python
from tools.tool_registry import ToolRegistry

# Initialize and auto‑discover all tools

registry = ToolRegistry()
registry.discover()

# 1. Group by capability

cap_cat = registry.capability_catalog()
video_tools = cap_cat.get("video_generation", [])

# 2. Group by provider

prov_cat = registry.provider_catalog()
elevenlabs_tools = prov_cat.get("elevenlabs", [])

# 3. Check tier health

tiers = registry.tier_summary()
core_available = tiers.get("CORE", {}).get("available", 0)

# 4. Build pre‑flight menu

menu = registry.provider_menu()
tts_available = menu["tts"]["available"]

# 5. Get compact summary for UI

summary = registry.provider_menu_summary()
print(f"Configured capabilities: {summary['capabilities']}")

```

## Summary

- **The Tool Registry** in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py) automatically discovers and registers all `BaseTool` subclasses via `pkgutil.walk_packages()`.
- **Six reporting methods** provide different grouping dimensions: capability, provider, tier, availability, and runtime status.
- **Capability and provider catalogs** organize tools by functional family and external service for browseable interfaces.
- **Tier summary and provider menus** support operational health checks and pre‑flight configuration validation.
- **Support envelope** delivers complete tool contract data for orchestrator‑level constraint validation.

## Frequently Asked Questions

### How does the Tool Registry automatically discover new tools?

The `discover()` method uses `pkgutil.walk_packages()` to traverse the `tools` package and instantiates every concrete subclass of `BaseTool`. This ensures any new Python file added under `tools/` is immediately available in all Tool Registry reporting methods without manual registration.

### What is the difference between `provider_menu()` and `provider_menu_summary()`?

The `provider_menu()` method returns a detailed nested structure with individual tool listings split by availability status, suitable for building interactive selection interfaces. The `provider_menu_summary()` method returns a compact roll‑up with counts, runtime support booleans, and warnings, optimized for quick agent onboarding displays.

### How are tool tiers and statuses defined in the registry?

Tools are categorized by the `ToolTier` enum (including `CORE`, `VOICE`, and `ENHANCE`) and `ToolStatus` enum to indicate operational state. The `tier_summary()` method queries these attributes to produce availability counts per tier, helping operators identify which functional areas require attention.

### Can I use these reporting methods without initializing the full orchestration stack?

Yes. The `ToolRegistry` class is self‑contained in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py). Instantiate `ToolRegistry()`, call `discover()`, and invoke any reporting method independently of the broader OpenMontage agent or orchestration layers, making them suitable for standalone diagnostic scripts and CI/CD validation.