Server has 12 tools with consistent Zod schemas and basic descriptions. All tools have input schemas with typed parameters and descriptions. However, descriptions are minimal (10-50 chars), lacking context on WHEN to use each tool or dependencies between them. Output schemas are not documented, LLMs cannot predict response structure. No error handling guidance, no idempotency hints, and no distinction between read-only and write operations in descriptions. Parameter descriptions are present but terse (e.g., 'Repository owner' vs 'The GitHub username or organization name of the repository owner'). Missing pagination details for list tools. No tool annotations (readOnlyHint/destructiveHint) despite clear risk stratification.

• Expand tool descriptions to 50-200 chars. Include WHAT the tool does, WHEN to use it, and any prerequisites. E.g., 'List workflow runs for a repository. Use this to find recent CI/CD executions; call getWorkflowRun for details on a specific run. Supports pagination (default 30 per page, max 100).'
• Document output schemas for all tools. Add a 'Returns' section to each tool description listing key fields (e.g., 'Returns: {id, status, conclusion, created_at, updated_at, ...}'). This enables LLMs to plan downstream tool calls.
• Add tool annotations: mark read-only tools with readOnlyHint=true, write tools with destructiveHint=true (for cancel/retry), and idempotent tools with idempotentHint=true. This guides LLM retry logic.
• Enhance parameter descriptions with format/constraint hints. E.g., 'owner: GitHub username or org name (alphanumeric, 1-39 chars)', 'issueNumber: positive integer, 1+', 'body: markdown text, max 65536 chars'.
• Add error handling guidance. E.g., 'If owner/repo not found, returns 404 with message. If rate-limited, returns 429 with retry-after header. If auth fails, returns 401, check GITHUB_TOKEN env var.'