This server has significant definition quality issues. All 8 tools use an aggregation pattern (action-based dispatch) which reduces clarity and forces LLMs to learn many action variants per tool. While schemas are present and mostly complete, descriptions are thin (averaging ~40 chars, well below the 194-char baseline), parameter descriptions are minimal or missing contextual details, and error handling provides no recovery guidance. Output schemas are not documented, LLMs cannot see what fields to expect or how to chain results. Security annotations and tool annotations (readOnlyHint, destructiveHint, idempotentHint) are absent. The naming pattern 'manage_X' is generic and does not reflect specific actions; LLMs must read the enum to understand what the tool actually does. Tool composition violates single-responsibility; each 'manage_*' tool bundles 8-11 distinct operations, forcing the LLM to infer which action to invoke rather than discovering tools by name.
Over-aggregation: All 8 tools use action-based dispatch with large enum values (6-12 actions per tool). This violates single-responsibility and forces LLMs to enumerate actions by reading schemas rather than discovering them by name. Recommended: split each 'manage_X' into verb_noun tools (e.g., 'search_projects', 'get_project', 'create_branch', 'delete_branch', 'list_branches', etc.).
All tool descriptions are 9 characters ('项目管理（聚合）' or equivalent), far below the 194-char baseline. Descriptions must answer: What does the tool do? When should I use it? What does it return? Current descriptions provide none of this. Required: expand to 50-200 chars explaining capabilities and when/why to invoke.
CRITICAL: Refactor from action-based dispatch (manage_X with large enums) to verb_noun naming. Split manage_projects into: search_projects, get_project. Split manage_branches into: list_branches, get_branch, create_branch, delete_branch, protect_branch, unprotect_branch, get_branch_protection, update_branch_lifecycle, list_branch_protection_members, add_branch_protection_member, update_branch_protection_member, remove_branch_protection_member. Similar split for other tools. This improves LLM discoverability and reduces cognitive load.
CRITICAL: Expand all tool descriptions to 50-200 characters. Include what the tool does, when to use it, and what it returns. Example: 'Search for Tencent Git projects by keyword. Returns id, name, path_with_namespace, description, and web_url. Use this to find a project before calling other tools that require project_id.'
CRITICAL: Document return type for every tool. Add to schema: 'Returns: <structure>' Example: 'Returns list of project objects with fields: id (number), name (string), path_with_namespace (string), description (string), default_branch (string), web_url (string).'
HIGH: Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to identify safe-to-retry and state-modifying operations. Example for delete_branch: add annotation {"destructiveHint": true} so LLMs know this cannot be undone without restore.
HIGH: Add error handling with recovery guidance. Wrap API calls in try-catch; categorize errors: 'Retryable' (429, 5xx) → suggest retry; 'User-fixable' (404, 400) → suggest search or parameter correction; 'Fatal' (403, 401) → check credentials. Example: 'Project "mygroup/myproject" not found. Available projects: [list]. Try search_projects() to find the correct project_id.'
No output schemas documented. LLMs cannot see what fields are returned or their types. This breaks tool chaining, if create_branch returns 'branch_id', the LLM needs to know that to pass it to downstream tools. Required: document return type for every tool (e.g., 'Returns object with fields: id, name, path_with_namespace, web_url').
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). LLMs cannot determine which tools are safe to retry, which modify state, and which are read-only. Required: add annotations to schema for all write operations (create_*, update_*, delete_*) and mark read-only tools explicitly.
No error handling or recovery guidance. When an API call fails (missing resource, permission denied, invalid parameter), the tool returns a raw error. LLMs cannot determine: Is this retryable? Should I ask the user? Did I pass a wrong parameter? Required: categorize errors (retryable, user-fixable, fatal) and provide actionable recovery hints (e.g., 'User not found. Try search_users() first').
Many optional parameters lack clear context on when/why to use them. Example: 'manage_branches' has 'developers_can_push' and 'developers_can_merge', when should each be true? What is the default? Required: document parameter interdependencies and defaults. Example: 'developers_can_push (optional, default true): If false, only maintainers can push to this branch. Used with protect action.'
Example values embedded in parameter descriptions (e.g., 'approver_rule' described as '-1:所有通过, 1:单人通过, 2+:多人通过'). LLMs tend to reuse example values literally. Required: replace with proper enum constraints in schema, not text descriptions.
Pagination parameters (page, per_page) present but no documentation of what happens when results exceed limits. Do results cap at 100? What is returned if no more pages? Required: document pagination behavior and include 'total_count' or 'has_next_page' in output.
TENCENT_GIT_TOKEN environment variable used for authentication but not documented in tool descriptions. LLMs may assume they need to pass a token as a parameter (bad practice). Required: document in server description that authentication is via TENCENT_GIT_TOKEN env var; ensure no tool accepts token as a parameter.
HIGH: Document parameter interdependencies and defaults. Example: 'developers_can_push (optional, default=true): Set to false to restrict push access to admins only. Only used with action=protect.'
MEDIUM: Replace example values in descriptions with enum constraints in schema. Example: instead of 'approver_rule' described as '-1:所有通过, 1:单人通过, 2+:多人通过', use schema: {"type": "enum", "values": [-1, 1, 2], "description": "Approval rule: -1 (any approver), 1 (single approver), 2+ (multiple approvers)"}'
MEDIUM: Document pagination behavior explicitly. Example: 'page (optional, default=1): Page number, starting at 1. per_page (optional, default=20, max=100): Results per page. Response includes total_count and has_next_page so you can iterate efficiently.'
MEDIUM: Ensure TENCENT_GIT_TOKEN and TENCENT_GIT_BASE_URL are documented only in server description (index.ts comments), not in tool parameters. Verify no tool accepts these as parameters.
MEDIUM: Add context on project_id format variations. Example: 'project_id (string): Project ID as number (e.g., "12345") or path (e.g., "mygroup/myproject"). If unsure, call search_projects() first.'
LOW: Consider breaking manage_comments into separate tools: list_comments, get_comment, create_comment, update_comment. Current action-based dispatch forces LLMs to learn the action enum rather than discovering by name.
LOW: Add examples in server description showing common multi-step workflows (e.g., 'To merge a PR: (1) search_projects, (2) list_merge_requests, (3) get_merge_request, (4) merge_merge_request'). This guides LLM planning.
LOW: Verify all numeric IDs (user_id, merge_request_iid, review_id) have type: number in schema. Some may be strings; clarify and constrain.