Single tool 'shortcut' with action dispatch pattern. Tool has a description and input schema with 12 parameters, but exhibits significant structural issues: (1) Tool name 'shortcut' is a noun, not a verb, violates naming convention and provides no hint about what the tool does. (2) Input schema uses union type for 'query' parameter and overloads parameter semantics across 8 actions, parameters are context-dependent and descriptions don't clearly explain which params apply to which actions. (3) Parameter descriptions are terse (20-40 chars) and lack actionable detail on valid ranges, formats, or interdependencies. (4) No output schema documented, LLMs cannot predict response structure. (5) Error handling returns only text in ToolResult but provides no recovery guidance or categorization. (6) Single monolithic tool violates composition pattern: should be split into search_stories, get_story, update_story, add_comment, create_story, get_epic, call_api, and help_shortcut.

• Split 'shortcut' into 8 separate tools: search_stories (action=search), get_story (action=get), update_story (action=update), add_story_comment (action=comment), create_story (action=create), get_epic (action=epic), call_shortcut_api (action=api), get_shortcut_help (action=help). Each tool name starts with a verb and declares one responsibility.
• For each refactored tool, document the output schema: e.g., search_stories returns {stories: [{id, name, state, owner, estimate, url}], total_count, limit}.
• Replace 'query' union type with action-specific parameters. search_stories accepts optional query string OR structured filters {owner, state, epic, iteration, type, archived}. Clearly state in description that structured filter overrides free-text query.
• Add enum constraint for 'owner' parameter in update_story and create_story: ['me', '<username>', '<mention_name>'] OR accept a string and document resolution logic in description.
• Expand parameter descriptions to 50-100 chars with format examples. E.g. 'id: Story or epic ID as number (704), prefixed string (sc-704), or Shortcut URL (https://app.shortcut.com/org/story/704).'
• Add min/max constraints for 'estimate' (0 - 13) and 'limit' (1 - 100) parameters in search_stories.
• Implement error categorization: return {isError: true, category: 'not_found'|'invalid_input'|'permission_denied'|'server_error', message: '...', suggestion: '...'} to guide LLM recovery.
• Document the Shortcut API filter object structure in search_stories description: 'filter: {owner?: string, state?: string, epic?: number, iteration?: number, type?: enum[feature|bug|chore], archived?: boolean}'.