Hermes Studio exposes 7 HTTP endpoints as MCP tools. All have descriptions (10-100 chars), but most are generic and lack actionable context. Input schemas are present for 5/7 tools but lack parameter descriptions, critical for LLM reasoning. Output schemas are entirely undocumented. No error handling guidance, no idempotency hints, no permission scopes declared. Tool names use HTTP verbs (GET/PUT/POST) rather than action verbs (get_servers, update_servers), which is non-standard for MCP. Composition is weak: no tool chains documented, no pagination guidance for list endpoints. Security: no mention of auth validation, secret injection, or audit logging in tool definitions.

• Rename tools to action-verb format: 'get_mcp_servers', 'update_mcp_servers', 'list_agents', 'create_agent', 'query_audit_trail', 'list_crews', 'create_crew'. This enables LLMs to infer intent from the name alone.
• Document output schemas for all tools. For GET /api/mcp/servers, specify: {servers: [{name: string, transport: 'stdio'|'http', url?: string, ...}], total: number}. For list endpoints, include pagination metadata (total, limit, offset).
• Add descriptions to all input parameters. For PUT /api/mcp/servers, describe each nested field: 'name (required, 1-100 chars): unique server identifier', 'transport (required): stdio or http', 'timeout (optional, ms): request timeout, default 30000'.
• Add error handling guidance to state-modifying tools. E.g., 'PUT /api/mcp/servers: Returns 400 if server name is empty or duplicate. Returns 500 if config.yaml is unwritable, check file permissions. Retry-safe: idempotent by server name.'
• Implement pagination for list endpoints. Add limit (1-100, default 20) and offset (default 0) parameters. Return {items: [...], total: number, limit: number, offset: number} to enable agent iteration over large result sets.