This server defines 2 tools with visible schemas and descriptions. Tool naming follows the pattern convention (verb_noun: 'home-assistant-states', 'home-assistant-switch'), but descriptions are sparse and lack detail required for LLM selection. Schemas are present and properly typed using Zod, but parameter descriptions are minimal and lack actionable constraints. Output format is implicit (text/plain) rather than explicitly documented. Error handling is absent, no guidance on failure modes or recovery. The server lacks composition guidance (chaining between tools) and does not document what the tools return, forcing LLMs to infer structure.
Tool descriptions lack guidance for LLM selection. Both descriptions are 1-2 sentences with no indication of WHEN to call each tool, what distinguishes them from similar operations, or what the caller should expect back.
Output schema is not documented. Both tools return {content: [{type: 'text', text: string}]}, but this structure is implicit in the code, not documented for the LLM. LLMs cannot infer how to parse or chain responses.
Parameter descriptions are too brief (10-35 chars). 'The entity ID to get state for' and 'The service to call' lack context on format, valid ranges, or dependencies. For 'home-assistant-states', it is unclear whether friendly_name search is fuzzy or exact, or what happens if multiple matches exist.
home-assistant-stateshome-assistant-switch
Recommendations
Expand tool descriptions to 100-200 characters. Example: 'home-assistant-states: Retrieve the current state of Home Assistant entities. Provide entity_id for a single entity, or friendly_name to search by display name (case-insensitive fuzzy match). Returns current state, last-changed timestamp, and attributes. Call this first to discover entity IDs before controlling switches.' This answers WHAT, WHEN, and HOW.
Document output schema explicitly for each tool. Example for home-assistant-states: 'Returns: {content: [{type: "text", text: string}]} where text is a formatted summary of matched entities: each line is "<entity_id> = <state> (last changed: <ISO-8601-timestamp>)". For friendly_name search, lists all matches or 'No entities found.'
Add constraint descriptions to parameters. Example: 'entity_id: The Home Assistant entity identifier (format: domain.name, e.g., switch.kitchen_light). Ignored if friendly_name is provided.' and 'friendly_name: Case-insensitive substring search for entity display names. Returns all matching entities; if multiple matches, list all options.',
Clarify mutual exclusivity and defaults for 'home-assistant-states'. Example: 'If both entity_id and friendly_name are provided, entity_id takes precedence. If neither is provided, return all entities (paginated if >50).'
Add error handling and recovery hints. Example: 'If entity not found by ID, returns 'Entity <entity_id> not found.' Try calling with friendly_name to search. If Home Assistant is unreachable, returns connection error and retry guidance.'
No error handling or recovery guidance. If Home Assistant API is unreachable, credentials are invalid, or an entity does not exist, the tools provide no guidance for the LLM on what to do next. No distinction between retryable and fatal errors.
No tool composition guidance. 'home-assistant-states' can search by friendly_name, but the search result does not document which fields are returned (entity_id? state? attributes?), so the agent cannot reliably extract the entity_id needed for 'home-assistant-switch'.
'home-assistant-states' accepts both entity_id and friendly_name as optional parameters, but descriptions do not explain mutual exclusivity, precedence, or required behavior (e.g., what if both are provided? What if neither is provided, does it return all states?). This undocumented dependency will cause LLM confusion.
Descriptions include example values ('switch.living_room_light', 'turn_on', 'turn_off'), which LLMs tend to reuse literally rather than adapt to context. Should use format constraints or enums instead. The 'turn_on' and 'turn_off' enum for 'service' is correct, but entity_id examples should not appear in parameter descriptions.
Parameter names do not follow type-suffix convention. 'entity_id' is clear, but 'friendly_name' could be clearer as 'entity_friendly_name' to avoid confusion with user names or other domain names in a multi-resource context.
home-assistant-states
Document the relationship between tools. Example: 'Typical workflow: (1) Call home-assistant-states with friendly_name to discover entity_id. (2) Extract entity_id from results. (3) Call home-assistant-switch with entity_id and desired service (turn_on or turn_off).'
Remove example values from descriptions and use enums/patterns instead. The service parameter already uses z.enum(), which is correct. Rewrite entity_id description without 'e.g., switch.living_room_light' example.
Add pagination and result limits if the API supports them. If home-assistant-states can return hundreds of entities, document a limit (e.g., 'Returns top 50 matches for friendly_name search; use entity_id for exact lookups') or add a 'limit' parameter.
Consider adding a 'get_attributes' parameter to home-assistant-states to control verbosity (basic state only vs full attributes), reducing token overhead for simple queries.
Document prerequisites and permissions. Example: 'Requires HOME_ASSISTANT_TOKEN and HOME_ASSISTANT_URL environment variables to be set. Token must have at least read:switch scope for home-assistant-states and write:switch scope for home-assistant-switch.'