domain_summary_tool
Generate a detailed summary of entities within a specified domain, including total count, state distribution, examples, and common attributes. Use this tool to preview available entities before querying or managing them in Home Assistant via Hass-MCP.
Instructions
Get a summary of entities in a specific domain
Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state
Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes
Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| example_limit | No |
Implementation Reference
- app/server.py:608-632 (handler)MCP tool registration and handler function for domain_summary_tool. Decorated with @mcp.tool() and @async_handler("domain_summary"). Delegates execution to the summarize_domain helper.@mcp.tool() @async_handler("domain_summary") async def domain_summary_tool(domain: str, example_limit: int = 3) -> Dict[str, Any]: """ Get a summary of entities in a specific domain Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available """ logger.info(f"Getting domain summary for: {domain}") return await summarize_domain(domain, example_limit)
- app/hass.py:333-397 (helper)Core helper function implementing the domain summary logic: fetches domain entities, computes state counts and examples, identifies top common attributes.async def summarize_domain(domain: str, example_limit: int = 3) -> Dict[str, Any]: """ Generate a summary of entities in a domain Args: domain: The domain to summarize (e.g., 'light', 'switch') example_limit: Maximum number of examples to include for each state Returns: Dictionary with summary information """ entities = await get_entities(domain=domain) # Check if we got an error response if isinstance(entities, dict) and "error" in entities: return entities # Just pass through the error try: # Initialize summary data total_count = len(entities) state_counts = {} state_examples = {} attributes_summary = {} # Process entities to build the summary for entity in entities: state = entity.get("state", "unknown") # Count states if state not in state_counts: state_counts[state] = 0 state_examples[state] = [] state_counts[state] += 1 # Add examples (up to the limit) if len(state_examples[state]) < example_limit: example = { "entity_id": entity["entity_id"], "friendly_name": entity.get("attributes", {}).get("friendly_name", entity["entity_id"]) } state_examples[state].append(example) # Collect attribute keys for summary for attr_key in entity.get("attributes", {}): if attr_key not in attributes_summary: attributes_summary[attr_key] = 0 attributes_summary[attr_key] += 1 # Create the summary summary = { "domain": domain, "total_count": total_count, "state_distribution": state_counts, "examples": state_examples, "common_attributes": sorted( [(k, v) for k, v in attributes_summary.items()], key=lambda x: x[1], reverse=True )[:10] # Top 10 most common attributes } return summary except Exception as e: return {"error": f"Error generating domain summary: {str(e)}"}