aws / aws/amazon-q-developer-cli
Add tool aliasing support for built-in tools (knowledge tool naming issue)
- Dominant language
- Rust
- Stars
- 2k
- Forks
- 439
- PR merge metrics
- No merged PRs in 30d
Description
### Checks
- [x] I have searched [github.com/aws/amazon-q-developer-cli/issues](https://github.com/aws/amazon-q-developer-cli/issues?q=) and there are no duplicates of my issue
- [x] I have run `q doctor` in the affected terminal session
- [x] I have run `q restart` and replicated the issue again
### Operating system
macOS 15.7.0 (24G222)
### Expected behaviour
Built-in tools should support aliases in agent configuration, similar to MCP tools. Users should be able to create descriptive aliases like "semantic-search" for the "knowledge" tool to improve discoverability and align with naming conventions.
### Actual behaviour
toolAliases only works for MCP server tools (@server/tool format). Built-in tools like "knowledge" cannot be aliased, forcing users to use generic names that don't convey functionality.
```
Based on the Q CLI documentation, **you cannot directly rename built-in tools like the `knowledge` tool**. Here's what the documentation reveals:
## **Built-in Tool Names Are Fixed**
The `knowledge` tool is a built-in tool with a fixed name. The documentation shows no mechanism to:
- Rename built-in tools
- Create aliases for built-in tools
- Override built-in tool names
## **What You CAN Do**
**1. Tool Aliases (MCP Only)**
The documentation shows `toolAliases` only work for MCP server tools:
\```json
{
"toolAliases": {
"@builder-mcp/InternalSearch": "search_internal",
"@sequential-thinking/sequentialthinking": "think_sequential"
}
}
\```
**2. Feature Request**
Since this is a significant usability issue (as your research showed), you should:
- Use `/issue` command to create a GitHub feature request
- Reference your comprehensive research findings
- Propose the tool aliasing system for built-in tools
**3. Workaround Options**
- Create an MCP server that wraps the knowledge tool functionality
- Use the existing `knowledge` name but improve documentation in your agents
- Wait for the Q CLI team to implement tool aliasing for built-in tools
## **Recommendation**
Your research identified a real problem. The best path forward is submitting a feature request through `/issue` with your analysis. The Q CLI team would likely be interested in implementing tool aliasing for built-in tools based on your evidence.
**References:**
- [Built-in Tools Documentation](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/built-in-tools.md)
[Tool uses: none]
> So I cannot use alias?
Correct - **you cannot use aliases for built-in tools like `knowledge`**.
The `toolAliases` feature only works for **MCP server tools** (tools with `@server/tool` format), not for built-in tools.
**What works:**
\```json
"toolAliases": {
"@builder-mcp/InternalSearch": "search_internal" ✅
}
\```
**What doesn't work:**
\```json
"toolAliases": {
"knowledge": "semantic-search" ❌
}
\```
You're stuck with the name `knowledge` until the Q CLI team adds aliasing support for built-in tools.
[Tool uses: none]
```
### Steps to reproduce
1. Create agent config with toolAliases for built-in tool: {"knowledge": "semantic-search"}
2. Try to use alias in agent - fails
3. Compare with MCP tool aliases which work correctly
### Environment
```yaml
[q-details]
version = "1.17.0"
hash = "1dd1004468c43f0e0c77d5c22c61839752883f2e"
date = "2025-09-29T19:39:39.613929Z (10h ago)"
[system-info]
os = "macOS 15.7.0 (24G222)"
chip = "Apple M4 Pro"
total-cores = 14
memory = "48.00 GB"
[environment]
cwd = "/Users/USER"
cli-path = "/Users/USER"
install-method = "toolbox"
[env-vars]
PATH = "/Users/USER/.toolbox/bin:/Users/USER/.config/smithy-mcp/mcp-servers:/opt/homebrew/sbin:/opt/homebrew/bin:/Users/USER/.toolbox/bin:/Users/USER/.config/smithy-mcp/mcp-servers:/opt/homebrew/sbin:/opt/homebrew/bin:/Users/USER/.config/smithy-mcp/mcp-servers:/opt/homebrew/sbin:/opt/homebrew/bin:/Users/USER/.config/smithy-mcp/mcp-servers:/opt/homebrew/sbin:/opt/homebrew/bin:/Users/USER/.local/bin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/homebrew/bin:/Applications/iTerm.app/Contents/Resources/utilities:/Users/USER/.local/bin"
QTERM_SESSION_ID = "76979b8532f94ae594a132c9a51fe2e5"
Q_SET_PARENT_CHECK = "1"
Q_TERM = "1.16.2"
SHELL = "/bin/zsh"
TERM = "xterm-256color"
__CFBundleIdentifier = "com.googlecode.iterm2"
[chat-settings]
[chat-trusted_tools]
@sequential-thinking/sequentialthinking=trusted
[chat-failed_request_ids]
none
[chat-context]
current_profile=q_cli_default
profile_context=
AmazonQ.md
AGENTS.md
README.md
.amazonq/rules/**/*.md
files=none
```
Contributor guide
Assessment
This issue has not been assessed yet.