aws / aws/amazon-q-developer-cli

bug: invalid JSON in agent-format.md `allowedTools` Examples block (JS `//` comments + unquoted `@builtin`) breaks copy-paste

Open Beginner friendly
#3,851 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] N/A — this is a documentation defect, not a runtime bug (`q doctor` not applicable)
- [x] N/A — this is a documentation defect, not a runtime bug (`q restart` not applicable)

### Operating system

N/A (documentation defect — applies on all platforms)

### Expected behaviour

The `allowedTools` "Examples" block in [`docs/agent-format.md`](https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md) is fenced as ```json, so copy-pasting it into an agent config file should produce a valid agent that loads.

### Actual behaviour

The block is not valid JSON, so pasting it into an agent config breaks loading. Agent files are parsed with strict `serde_json::from_str` — `crates/agent/src/agent/agent_config/mod.rs:243` (`match serde_json::from_str(&entry_contents)`; a second loader at `:371`), which rejects both comments and bare/unquoted tokens.

Two problems in the block (`docs/agent-format.md`, `### Examples`, lines ~219–244):

1. **JS-style `//` comments** on most lines (e.g. `// Exact matches`, `// All filesystem tools`). JSON has no comment syntax.
2. **Unquoted bare token** `@builtin,` (line 231) — it must be the string `"@builtin"`. The same document quotes it correctly elsewhere: the field-name list at line 124 (`Use \`@builtin\` to include all built-in tools`) and the prose at line 215.

Verified the failure independently with a JSON parser:

```
$ python3 -c "import json,sys; json.load(open(sys.argv[1]))" allowedtools-example.json
json.decoder.JSONDecodeError: Expecting value: line 3 column 5
```

(line 3 = the first `// Exact matches` comment).

### Steps to reproduce

1. Open `docs/agent-format.md`, copy the ```json fenced block under `### Examples` (the `allowedTools` example).
2. Save it as e.g. `~/.aws/amazonq/cli-agents/example.json` (or paste the `allowedTools` array into an existing agent file).
3. The agent fails to parse — `serde_json` rejects the `//` comments and the unquoted `@builtin` token. Equivalent parser check: `python3 -c "import json; json.load(open('example.json'))"` → `Expecting value: line 3 column 5`.

### Why it matters

The "Examples" block is the canonical reference a user reaches for when authoring `allowedTools`, and it is fenced as JSON, so it reads as copy-pasteable. Because agent configs are parsed with strict `serde_json` (no comment/trailing-comma leniency), the documented example cannot round-trip. We hit this while building a cross-platform agent-config adapter that emits these files as strict JSON: the documented form our integration pointed implementers at simply does not parse.

This is a sibling of the existing docs-accuracy gap on the same file, #3231 (the `name` field is no longer optional) — both are cases where `agent-format.md` drifted from what the loader actually accepts.

### Proposed fix

Move the explanatory `//` annotations into prose/bullets above the snippet (or drop them), and quote the token as `"@builtin"`, leaving a strictly-valid block:

```json
{
"allowedTools": [
"fs_read",
"knowledge",
"@server/specific_tool",
"fs_*",
"execute_*",
"*_test",
"@builtin",
"@server/api_*",
"@server/read_*",
"@git-server/get_*_info",
"@*/status",
"@fetch",
"@git-*"
]
}
```

The per-entry meanings (exact match / native wildcard / `@builtin` = all native tools / MCP wildcards / server-level) are already explained in the surrounding "Pattern Matching Rules" and the bullet list at lines 119–125, so no information is lost by removing the inline comments.

I'm happy to open a PR with this change if that's welcome.

### Environment

N/A (documentation defect)

Contributor guide

Open the contributing guide

Research direction

Open docs/agent-format.md and inspect the allowedTools Examples block under the Examples heading. Remove the inline comments and ensure the @builtin entry is quoted, then validate the copied block with Python's JSON parser. Done means the fenced example is strict, copy-pastable JSON that the agent loader accepts.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.