domain_summary_tool

Instructions

Implementation Reference

• app/server.py:671-694 (handler)

  The MCP tool handler registered as 'domain_summary'. It takes a domain (e.g., 'light') and an optional example_limit (default 3), logs the call, and delegates to the summarize_domain helper function.

  @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:380-444 (helper)

  Core business logic for the tool. Fetches all entities for the given domain, counts state distribution, collects example entities per state (up to example_limit), and identifies the top 10 most common attributes. Returns the summarized dictionary.

  @handle_api_errors
  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)}"}

• app/server.py:671-672 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool. The @async_handler('domain_summary') decorator provides logging.

  @mcp.tool()
  @async_handler("domain_summary")

• app/server.py:673-694 (schema)

  Input schema: domain (required string), example_limit (optional int, default 3). Output schema: dict with total_count, state_distribution, examples, and common_attributes.

  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)