Teamflow-mcp has 6 tools with basic schemas and descriptions, but significant gaps prevent higher scores. All tools have descriptions (10-100 chars, mostly adequate), and input schemas are present with Zod validation. However, parameter descriptions are sparse or missing entirely (e.g., notion_create_page 'title' param has null description; slack_post_message 'channel' and 'text' lack descriptions; jira_search 'max' and jira_create_issue 'project_key'/'summary' lack descriptions). Output schemas are not documented, responses are free-text strings without structured field definitions. Error handling returns generic fail() messages without recovery guidance. No tool annotations (readOnlyHint/destructiveHint) despite clear read/write distinctions. Naming is verb-noun compliant but generic (e.g., 'notion_search' vs 'search_notion_pages'). No pagination support despite search tools returning lists. Missing parameter constraints (e.g., no enum for issue_type despite mentioning 'Task'/'Bug'). Composition is reasonable, tools are single-purpose, but output lacks IDs needed for chaining (e.g., notion_create_page returns only title and ID in text, not structured JSON).

• Add descriptions to all 7+ undescribed parameters. E.g., slack_post_message.channel: 'Slack channel ID (e.g., C123456) or name (e.g., #general). The bot must be a member of the channel.'
• Convert all tool responses from free-text strings to structured JSON objects. E.g., notion_create_page should return {title: string, id: string, url: string} instead of 'Created page "X" id=Y'. Document output schema in tool definition.
• Add tool annotations: readOnlyHint=true for notion_search, slack_list_channels, jira_search; destructiveHint=true for notion_create_page, slack_post_message, jira_create_issue. Use server.tool(..., {...}, {...}, {...}, {readOnlyHint: true}).
• Enhance error messages with recovery guidance. Catch specific error types (401 auth, 404 not found, 429 rate limit) and return actionable messages. E.g., 'Channel not found. Available channels: #general, #dev. Did you mean one of these?'
• Add pagination to list/search tools: return {items: [...], total_count: number, has_more: boolean, next_cursor?: string} and accept cursor/offset parameters. Cap results at 20-50 items per call to avoid context bloat.