Azure MCP Server has 15 tools with consistent naming (verb_noun pattern: get_, list_, create_, delete_, upload_, download_, restart_, start_, stop_). All tools have descriptions (avg ~50 chars, baseline 194 chars) and input schemas with type definitions and parameter descriptions. However, descriptions are significantly below the 194-char baseline and lack context on WHEN to use each tool, prerequisites, or recovery guidance. No output schemas are documented. Error handling is minimal, no recovery guidance, no categorization of retryable vs fatal errors. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels (READ_ONLY, WRITE, DESTRUCTIVE). Schemas use Zod types but lack enums, ranges, or format constraints. No pagination support on list tools despite potential for large result sets.

• Expand tool descriptions to 100 - 200 characters. Include WHAT the tool does, WHEN to use it (vs similar tools), and WHAT it returns. Example: 'Get configuration of an Azure App Service (alwaysOn, appSettings, connectionStrings, etc.). Use this to inspect runtime settings; call azure_apps_get for deployment details instead.'
• Document output schemas for all tools. Declare the structure of returned objects, field types, and which fields are safe to pass to downstream tools. This enables LLMs to chain calls without guessing.
• Add tool annotations: mark READ_ONLY tools with readOnlyHint=true, WRITE tools with idempotentHint=true (if safe to retry), and DESTRUCTIVE tools with destructiveHint=true. This signals to agents which calls are safe to retry and which require confirmation.
• Add pagination to list tools: include limit (default 20, max 100) and offset/cursor parameters. Return total_count or next_cursor in responses. Document the limit in the tool description.
• Implement structured error responses with recovery guidance. Example: 'Resource Group "mygroup" not found. Available groups: [list]. Call azure_apps_list to discover valid names.' Categorize errors as retryable (network timeout) vs user-fixable (invalid name) vs fatal (permission denied).