This server has only 1 tool with minimal schema definition. The tool name is appropriate (verb_noun pattern: 'get_clerk_user_data'), and has a short description (44 chars), but the tool registration in app/[transport]/route.ts shows NO input schema whatsoever. The tool accepts authInfo via context (not explicit parameters), making it impossible for clients to understand what inputs are required or what format they expect. The description is too vague ('Gets data about the Clerk user that authorized this request'), it does not explain WHEN to call it, what the return structure is, or what fields the response contains. There is no documented output schema. No error handling guidance. Security: the tool relies on server-side token verification via withMcpAuth, which is correct, but the tool definition itself provides no indication of required permissions or scope.

• Add explicit input schema to tool registration. Even if the tool uses context-based auth, define any parameters (e.g., user_id, format, fields) as JSON Schema with type, description, and constraints. Example: { 'type': 'object', 'properties': { 'user_id': { 'type': 'string', 'description': 'Clerk user ID (optional; defaults to authenticated user)' } }, 'required': [] }
• Expand description to 100-150 chars. Include: (1) WHAT it does ('Retrieves the authenticated Clerk user's profile data'); (2) WHEN to use it ('Call this to get the current user's email, name, and profile metadata'); (3) Prerequisites ('Requires valid Clerk authentication token').
• Document the return structure. Define what fields are in the userData object (e.g., id, email_addresses, primary_email_address, first_name, last_name, created_at, etc.). Return this as structured JSON, not a stringified dump.
• Add error handling to the tool implementation and document it. Catch auth failures, not-found errors, and API timeouts. Return actionable error messages: 'Authentication failed: invalid or expired token. Re-authenticate and retry.' or 'User not found. Check that the token corresponds to a valid Clerk user.'
• Declare required permissions in tool metadata. Add a scope or permission field to the registration: e.g., 'permissions': ['read:user_profile']. Document in the description what the agent is allowed to do.