Single tool with a descriptive name and basic schema, but parameter descriptions are missing critical detail. Input schema uses Zod and is properly typed. Output schema is unstructured (rich metadata objects without type guarantees). Error handling exists but lacks actionable recovery guidance. No tool annotations (readOnlyHint, idempotentHint). The server does implement proper secret injection (env vars for auth) and follows a stateless request model, but the tool definition falls short of production-grade standards.

• Add explicit output schema documentation in handler comments. Example: 'Returns { content: [{ type: 'resource', resource: { text: filename, uri: webUrl, mimeType, metadata: { id, size, createdBy, lastModifiedBy, lastModified, shared } }}], _meta: { usedFallback: bool, fileCount: int, query: string, userId: string }, isError: false }'
• Enhance 'user' parameter description: 'User's UPN (e.g. [email protected]) or object ID (UUID). If omitted, defaults to the first user in the tenant.'
• Return structured error messages on Graph API failures. Instead of silent fallback, return: { content: [{ type: 'text', text: 'Primary search failed (HTTP 503). Retrying with fallback...' }], _meta: { usedFallback: true, error: 'Service temporarily unavailable' }, isError: false }. This lets the LLM understand degradation.
• Add readOnlyHint: true to the tool schema registration to signal immutability.
• Add limit parameter (default 20, max 100) to control result count and support pagination via offset. Document: 'Limit results to N items (1-100, default 20). Use offset to paginate.'
• Document fallback strategy in the tool description: 'If Graph search API is unavailable, falls back to filtering a directory listing. Fallback may not respect all query operators.'
• Validate 'query' parameter length (e.g. 1-255 chars) and reject empty or null queries explicitly.
• Add a result count limit and return _meta.totalAvailable to signal when results are truncated.