aws / aws/amazon-q-developer-cli

Add tool aliasing support for built-in tools (knowledge tool naming issue)

Open
#3,053 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.