This server has critical definition quality issues. All 5 tools lack input parameter descriptions and proper schema documentation. While tools are properly named with action verbs (find_, analyze_, identify_), the descriptions are minimal (10-50 chars, well below the 194-char baseline for production tools). Most critically, 4 of 5 tools have empty input schemas ({}) with no parameters defined, violating fundamental parameter documentation requirements. Only identify_stale_accounts has a single parameter with a type and description. Error handling is completely absent, tools return API errors as-is without recovery guidance or categorization. Output schemas are not documented anywhere, leaving LLMs to guess response structures. No tool has security annotations, scope declarations, or audit trail logging.
4 of 5 tools have empty input schemas ({}), no parameters defined, documented, or validated. This violates the fundamental requirement that every parameter must have a type and description.
No tool descriptions explain when to use the tool or what it returns. Descriptions are 10 - 50 chars (well below 194-char baseline), providing insufficient context for LLM tool selection.
Output schemas are not documented. LLMs cannot infer response structure from the code; they need explicit documentation of what fields to expect and how to chain results to downstream tools.
Add comprehensive input parameter descriptions to all tools. Even tools with no current parameters (find_privileged_users, analyze_mfa_status, etc.) should document why they accept no input and what assumptions they make about the data source.
Expand tool descriptions to 100 - 250 chars following the production baseline (194-char average). Each must answer: What does this do? When should the LLM call it? What problem does it solve? Example: 'Identify users assigned to high-privilege Azure AD roles (Global Administrator, Privileged Role Administrator, etc.). Call this to assess security risk from overly-permissioned accounts and recommend least-privilege remediation.'
Document output schemas for each tool. For find_privileged_users, explicitly state: 'Returns {privilegedUsers: [{displayName, userPrincipalName, roles: [string]}], totalCount: integer}'. This enables LLMs to chain results and extract needed fields.
Implement structured error handling. Wrap call_roadrecon_api() with try-catch that categorizes errors (retryable: timeout/5xx; user-fixable: 404/invalid-param; fatal: auth-failure). Return actionable error objects: {error: 'User not found', retryable: true, suggestion: 'Try calling analyze_groups() to list available users first'}.
Add result pagination to analyze_mfa_status and analyze_groups. Accept optional limit (default 50, max 500) and offset parameters. Return total_count and a next_offset if more results exist. This prevents context-window exhaustion on large tenants.
Implement rate limiting and audit logging. Log each tool call (tool_name, timestamp, user_id, result_count) to stderr. Rate-limit to 10 calls/minute per tool to prevent runaway agents from overwhelming ROADrecon.
Error handling completely absent. Tools return raw API errors ({"error": str(e)}) with no recovery guidance, categorization, or actionable hints for the agent.
No security annotations, permission gates, or audit trails. Tools accept zero input parameters, but underlying ROADrecon API calls are not rate-limited, logged, or permission-checked.
No pagination or result limits. Tools return entire datasets from ROADrecon (all users, all groups, all apps). A tenant with 10,000 users could return a response that exhausts context windows and invites LLM hallucination.
Add tool annotations (readOnlyHint: true for all tools, since none modify state) to signal to clients that these are safe to retry and stateless.
For identify_stale_accounts, validate the 'days' parameter: enforce minimum=1, maximum=365, and return a validation error if the user passes invalid values (e.g., days=-5 or days=999).
Add a discovery/info tool (e.g., get_tenant_summary) that returns key tenant statistics (total_users, total_groups, total_apps, mfa_adoption_rate) without full result lists. This enables LLMs to understand scope before requesting filtered analyses.
Document the ROADrecon API dependency explicitly. State that the server requires a running ROADrecon instance at ROADRECON_URL and what API endpoints it expects (users, mfa, directoryroles, applications, groups).