TunnelHW exposes 4 tools for relay credential management. All tools have descriptions (10-50 chars, below the 50-200 char baseline for LLM optimization) and input schemas with typed parameters. However, critical gaps undermine usability: (1) descriptions are minimal and lack WHEN/WHY context; (2) no output schemas documented; (3) parameter descriptions are terse (avg 40 chars vs 72 baseline); (4) no error handling guidance; (5) no tool annotations (readOnlyHint/destructiveHint); (6) no pagination or result limits despite list_agents potentially returning many items. The 'state-dir' parameter appears in all tools but is never explained, is it a path? A config key? This forces LLMs to guess. Risk labels (WRITE/READ_ONLY) exist but are not exposed in tool definitions, so agents cannot reason about side effects.

• Expand tool descriptions to 80-150 chars. Example: 'pair-token: Generate a single-use token to pair a new agent with this relay. Call this once per agent. Returns a token valid for 1 hour. Requires write access to state-dir.'
• Document output schemas for all tools. E.g., pair-token returns {token: string, expires_at: ISO8601, agent_id: string}; agents returns {agents: [{id, name, paired_at, last_seen}], total: int}.
• Clarify 'state-dir' parameter: 'Absolute or relative filesystem path to the relay's credential directory. Must be readable/writable. E.g., /etc/tunnelhw/relay or ./state.'
• Add tool annotations: mark pair-token, api-token, revoke-agent with destructiveHint=true; mark agents with readOnlyHint=true. This enables agents to reason about retry safety and side effects.
• Add pagination to agents: accept optional limit (1-1000, default 50) and offset parameters; return {agents: [...], total: int, has_more: bool}. Prevents context window exhaustion.