Agent name "mlx" causes tool access failure despite valid configuration

[jordan-stoner]

Checks

• I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
• I have run q doctor in the affected terminal session
• I have run q restart and replicated the issue again

Operating system

macOS 15.6.1 (24G90)

Expected behaviour

Agent named "mlx" should work with standard configuration like other agent names. The configuration {"name": "mlx", "tools": ["*"]} should provide full tool access without warnings or dummy tool fallback.

Actual behaviour

Agent named "mlx" fails to load tools properly, showing only dummy tool access and generating toolsSettings warnings even with minimal configuration. The exact same configuration works perfectly when agent is renamed to "mlx-dev" or "test-agent".

[chat-transcript]
> [test-agent] > do you have access to all your tools> 
> 
> 
> 
> 
🛠️  Using tool: introspect (trusted)> 
 ⋮ > 
 ● Introspecting to get you the right information> 
 ⋮ > 
 ● Completed in 0.0s> 
> 
> 
> Yes, I have access to all my built-in tools. Here's what I can do:> 
> 
File Operations:> 
• fs_read - Read files, directories

Perfect! The test-agent has full tool access, which proves Q CLI itself is working fine. The issue is specifically with the mlx agent configuration.

Since the test-agent works with just `{"tools": ["*"]}`, but mlx doesn't work even after recreation, there must be something about the mlx agent name or configuration that's causing conflicts.

**Quick fix:** Rename the mlx agent to something else:
[Tool uses: execute_bash]

> y


[Tool uses: fs_write]

> y

Now try `q chat --agent mlx-dev` - this should work with full tool access since it's essentially the same minimal config as test-agent but with your MLX-specific prompt and resources.
[Tool uses: none]

> that worked. Does the mlx-dev agent still have a line of startup code in its config script to read all the project documentation on startup?


[Tool uses: fs_read]

Yes, it has both:

1. **Prompt instruction**: "Upon startup, familiarize yourself with the project by reading README.md and key documentation files"

2. **Resources section**: 
   - `file://README.md` - automatically loads the main README
   - `file://.amazonq/rules/**/*.md` - loads all markdown files in the rules directory

So the mlx-dev agent will automatically read the project documentation on startup through the resources section, and the prompt tells it to familiarize itself with the project structure and workflow.
[Tool uses: none]

> so is "mlx" a reserved agent name?

That's a great question. The evidence suggests "mlx" might be a reserved or problematic agent name:

1. **test-agent** worked perfectly with minimal config
2. **mlx** failed with the exact same config 
3. **mlx-dev** works perfectly with the same config
[Tool uses: introspect]

The documentation doesn't explicitly mention any reserved agent names or naming restrictions. However, the behavior we observed strongly suggests "mlx" may conflict with something in the Q CLI system.

Possible explanations:
1. **Internal conflict**: "mlx" might conflict with Apple's MLX framework references in Q CLI
2. **Cached configuration**: There could be system-level caching of the "mlx" name
3. **Hidden system agent**: There might be an internal or system agent using that name

Since the documentation doesn't specify reserved names, this appears to be an undocumented limitation. The safest approach is to avoid short, common technology names like "mlx" for agent names and use more descriptive names like "mlx-dev", "mlx-chat", or "mlx-assistant".

---
*Reference: [Agent File Locations Documentation](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-file-locations.md)*
[Tool uses: none]

> can you suggest this as a bug to AWS


[Tool uses: report_issue]

(...truncated)

Steps to reproduce

1. Create agent config at .amazonq/cli-agents/mlx.json with minimal config: {"name": "mlx", "tools": ["*"]}
2. Launch with q chat --agent mlx
3. Agent shows dummy tools only and toolsSettings warnings
4. Rename agent to mlx-dev.json and update name field
5. Launch with q chat --agent mlx-dev
6. Agent works perfectly with full tool access

This suggests "mlx" may be a reserved or problematic agent name, but this is not documented anywhere.

Environment

<This will be visible to anyone. Do not include personal or sensitive information>

[q-details]
version = "1.15.0"
hash = "a8a0426eaff32ac9b1599ca1b1f1881ffd16054d"
date = "2025-09-02T17:15:25.464923Z (5d ago)"

[system-info]
os = "macOS 15.6.1 (24G90)"
chip = "Apple M1 Max"
total-cores = 10
memory = "64.00 GB"

[environment]
cwd = "/Volumes/Media/AI/q"
cli-path = "/Volumes/Media/AI/q"
install-method = "unknown"

[env-vars]
PATH = "/Users/USER/bin:/opt/anaconda3/bin:/opt/anaconda3/condabin:/Users/USER/.npm-global/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:/Users/USER/.local/bin:/Users/USER/.lmstudio/bin"
QTERM_SESSION_ID = "392c8df8d8d34e26b175b1e1072cc41d"
Q_SET_PARENT_CHECK = "1"
Q_TERM = "1.15.0"
SHELL = "/bin/zsh"
TERM = "xterm-256color"
__CFBundleIdentifier = "com.apple.Terminal"

[chat-settings]


[chat-trusted_tools]
fs_read=trusted

[chat-failed_request_ids]
none

[chat-context]
current_profile=default
profile_context=
AmazonQ.md
README.md
.amazonq/rules/**/*.md

files=
/Volumes/Media/AI/q/README.md, 2520 tkns
total context size=2520 tkns