This server has 10 read-only tools for the Upstox trading API. While all tools are present with schemas and basic descriptions, there are significant gaps in definition quality that prevent this from being production-ready. All tools are named with the 'get_' verb (good naming convention), but descriptions are brief and lack context about when to use each tool or what makes them distinct. Parameter descriptions are minimal, most just say 'Access token is required' or 'Order ID is required' without explaining formats, constraints, or why the parameter matters. Output schemas are not documented in the code, we see the input Zod schemas but not what fields are returned or how the agent should interpret results. Error handling is absent; tools throw generic 'Error occurred while calling Upstox API' messages that give agents no recovery guidance. The server also exposes access tokens as tool parameters (critical security issue), violating pattern:secret-injection. No tool annotations (readOnlyHint, idempotentHint) are present to guide agent reasoning about retry safety and side effects, though all tools are READ_ONLY so they should be marked as such.

• CRITICAL: Move access tokens from tool parameters to server-side configuration. Use environment variables or a vault service to inject tokens at runtime. Remove the accessToken parameter from all tools and instead retrieve it from the server context or _meta field.
• Expand tool descriptions to 100-250 characters. For example, instead of 'Retrieve user profile information from Upstox', write: 'Fetch the authenticated user's profile including account type, subscription status, and broker details. Use this first to verify user identity and account permissions before accessing portfolio or trading data.'
• Add structured output documentation. In the tool definition or a docstring, describe what fields are returned. E.g. for get-profile, document: 'Returns {user_id, email, name, account_type, status, subscription_status}'.
• Enhance error handling. Instead of throwing a generic error, catch API errors and return structured responses like: '{isError: true, content: [{type: "text", text: "User not found. Verify the access token is valid and try again."}]}'.
• Document parameter constraints and formats in descriptions. E.g. 'orderId: A numeric or alphanumeric order identifier from the Upstox order system. Required to retrieve order-specific trades or details.'
• Add tool annotations to the server.tool() registration. All 10 tools should include readOnlyHint: true since they are read-only. For idempotent tools (all of these are), add idempotentHint: true.
• Clarify tool distinctions in descriptions. Explain when to use get-order-trades (trades for a specific order) vs get-trades (all trades for the day), and when to use get-holdings (long-term positions) vs get-positions (short-term positions).