Improve tool descriptions and fix translation key collision for AI agent guidance - #142
Open
ma1728 wants to merge 3 commits into
Open
Improve tool descriptions and fix translation key collision for AI agent guidance#142ma1728 wants to merge 3 commits into
ma1728 wants to merge 3 commits into
Conversation
added 2 commits
July 1, 2026 17:15
… field - Clarify add_issue_comment is for supplementary comments, not primary content - Enhance description field hints in add_issue and update_issue - Help AI agents prefer the description field over adding comments Closes nulab#141
…slations - Introduce TOOL_ADD_ISSUE_DESCRIPTION_FIELD and TOOL_UPDATE_ISSUE_DESCRIPTION_FIELD to avoid key collision with tool-level descriptions - Update .backlog-mcp-serverrc.json.example with Japanese translations - Ensure the improvement works for Japanese users using translation config
ma1728
changed the title
Collaborator
|
@ma1728 The wording changes I'd like to hold off on. Not everyone uses Backlog the way your team does. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves tool description strings so that AI agents (Claude, GPT, etc.) are guided to use the
descriptionfield inadd_issue/update_issueinstead of writing primary issue content viaadd_issue_comment.Also separates translation keys for parameter-level descriptions to avoid collisions with tool-level descriptions, and provides Japanese translations.
Closes #141
Changes
addIssueComment.ts— Tool-level descriptionBefore:
"Adds a comment to an issue"After:
"Adds a supplementary comment to an existing issue. Use this for follow-up notes, status updates, or discussion — not for the primary issue description. To set or update the main issue content, use add_issue or update_issue with the description field instead."addIssue.ts—descriptionparameterTOOL_ADD_ISSUE_DESCRIPTION_FIELD(previously sharedTOOL_ADD_ISSUE_DESCRIPTIONwith the tool-level description)"Detailed description of the issue""Detailed description of the issue. This is the primary field for explaining the issue context, requirements, and acceptance criteria. Prefer this over adding a comment."updateIssue.ts—descriptionparameterTOOL_UPDATE_ISSUE_DESCRIPTION_FIELD(previously sharedTOOL_UPDATE_ISSUE_DESCRIPTIONwith the tool-level description)"Detailed description of the issue""Detailed description of the issue. Use this to set or update the main issue content rather than adding a comment.".backlog-mcp-serverrc.json.example— Japanese translationsTOOL_ADD_ISSUE_COMMENT_DESCRIPTIONTOOL_ADD_ISSUE_DESCRIPTION_FIELDTOOL_UPDATE_ISSUE_DESCRIPTION_FIELDWhy separate translation keys?
Previously,
TOOL_ADD_ISSUE_DESCRIPTIONwas used for both the tool-level description ("Creates a new issue...") and the parameter description ("Detailed description of the issue"). When a user set a Japanese translation for this key, both contexts received the same string — which made no sense for the parameter. The new*_FIELDkeys resolve this.Testing
All 396 tests pass (
pnpm test).