15+ tools completely lack descriptions in provided source code (user_management, role_management, group_management, health_check, search, fetch, list_example_reports, get_secret, get_folder, etc.). This prevents LLMs from understanding when to invoke these tools.
Recommendations
Add explicit input and output schemas to all 20 undocumented tools in server.py. Each tool must have a `Tool` registration with name, description, and `InputSchema` with typed parameters. Reference the pattern from platform_user_management and search_platform_user.
Write substantive descriptions for all 15 tools currently lacking them. Follow the 10 - 1024 character guideline and answer: What does the tool do? When to use it? What does it return? Example: 'Delete a group by ID and optionally remove all member associations. Returns {success: bool, removed_members: int, errors: [str]}.'
Rename ambiguous tools to follow verb_noun convention: 'search' → 'search_resources' or split into search_users, search_secrets, search_folders (which already exist separately). 'fetch' → 'fetch_resource' or 'get_resource'. 'user_management' → 'update_user' or 'manage_user_lifecycle' with explicit action parameter enum.
Add parameter descriptions for all management tools. For user_management, role_management, etc., document: action enum ('create'|'delete'|'update'|'get'|'search'), required vs optional params per action, expected data schema for create/update. Example: 'action: Required. One of: create, delete, update, get, search. Controls the operation type.'
Document output schemas in tool descriptions. Example for platform_user_management: 'Returns {result: {id: str, created_at: ISO8601, ...}, verification: {user_found: bool, ...}}' so LLMs know what to expect and can chain calls.
Add error recovery guidance to all tools. When ValueError or network errors occur, return structured error: {error: str, recovery: str, retry_params: {...}}. Example: 'Invalid JSON data. Retry with valid JSON object. Expected keys: Name, Username, Email.'
Generic and overly broad tool names: 'search', 'fetch', 'user_management', 'role_management' do not follow verb_noun convention and are ambiguous. LLMs cannot distinguish search (generic) from search_users, search_secrets, search_folders without extensive disambiguation reasoning. This violates the naming clarity baseline (90% of A+ tools use action verbs, most common: get, list, create, search, update).
No output schemas documented for any tool. LLMs cannot plan downstream calls or extract required fields. All 25 tools lack documented return types, violating the baseline that 100% of A+ tools have documented return types.
No error recovery guidance. The visible tools (platform_user_management, search_platform_user) return raw JSON or error dicts without actionable recovery hints. E.g., 'Invalid JSON data' error on platform_user_management does not guide LLM to retry with different input format.
SQL query generation and execution tools (generate_sql_query, run_report, ai_generate_and_run_report) lack input validation and SQL injection safeguards. No mention of prepared statements, query rate limits, or result set caps. SQL tools are high-risk vectors for both data exfiltration and DOS.
Credentials and tokens visible in tool implementation code (platform_hostname, service account, password, tenant_id are environment variables used directly in tools). No evidence of token expiry handling, refresh logic, or secure caching. OAuth token in _build_headers() is cached globally without TTL or refresh.
Destructive write operations (user_management, role_management, group_management, folder_management with delete/update actions) lack confirmation or dry-run support. No mention of permission gates or audit trails. An LLM could delete users or groups without safeguards.
Implement SQL injection safeguards for generate_sql_query and run_report. Use parameterized queries, validate generated SQL against allowlist, or restrict to read-only report templates. Add rate limits and result caps (e.g., 1000 rows max).
Add confirmation step for all write operations. Implement dry_run parameter or separate preview_user_delete, preview_group_delete tools that return what would be deleted without executing. Require explicit confirmation before irreversible actions.
Implement proper OAuth token lifecycle management: add TTL tracking, automatic refresh before expiry, and retry logic on 401. Current global _headers cache has no expiry and will fail silently after token expires.
Add audit logging to all write tools. Log caller identity, timestamp, action, parameters, and result for compliance and incident investigation. Implement permission gates (e.g., require admin role for delete operations).
For search and list tools, add pagination support. Accept page, limit, and offset parameters.
Add tool annotations to MCP tool registration. Mark platform_user_management and management tools with destructiveHint: true. Mark all write tools with idempotentHint for create/update operations to signal retry-safety.
Consolidate overlapping tools. If search, search_users, search_secrets, search_folders all exist, create a single search tool with a resource_type enum parameter to reduce LLM disambiguation overhead.
Add input validation constraints to parameter descriptions. For example: 'page_size: Integer between 1-100, default 20' or 'action: Enum. Must be one of: create, delete, update, get, search.'
Create a discovery/help tool (e.g., list_tools, explain_tool) that summarizes available operations, expected parameters, and common workflows. This reduces LLM's need to infer intent from names alone.