Checks

• I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
• N/A — this is a documentation defect, not a runtime bug (q doctor not applicable)
• 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 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:

{
  "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)