📝 Documentation drift detected — `tools` field incorrectly marked unimplemented; `service-connection` option undocumented

[github-actions]

Documentation Freshness Audit

The weekly documentation audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Front Matter Fields	tools: field marked as RESERVED / not yet implemented in docs, but is fully implemented and tested in code	AGENTS.md, src/compile/common.rs, src/compile/types.rs
MCP Server Config (1ES)	service-connection: option under mcp-servers entries is supported in code but completely undocumented	AGENTS.md, src/compile/onees.rs, src/compile/types.rs

Details

1. tools field incorrectly marked as RESERVED

The documentation shows the tools front matter field as a commented-out, not-yet-implemented stub:

# tools:                       # RESERVED: tool configuration (not yet implemented)
#   bash: ["cat", "ls", "grep"]  # bash command allow-list
#   edit: true                   # enable file editing tool

However, src/compile/common.rs in generate_copilot_params() fully implements this feature:

• tools.edit — when false, suppresses --allow-tool write (defaults to true)
• tools.bash — controls which shell commands are exposed:
  • Omitted → default safe command list (cat, date, echo, grep, etc.)
  • [":*"] → unrestricted shell access (--allow-tool "shell(:*)")
  • [] → bash completely disabled
  • Explicit list → only those commands allowed

There are also dedicated unit tests for this behavior (test_copilot_params_bash_wildcard, test_copilot_params_bash_disabled).

Users reading the docs will assume this feature doesn't work and won't use it, even though it is fully functional.

2. service-connection option undocumented for 1ES MCPs

src/compile/types.rs defines a service_connection field in McpOptions:

/// Service connection name (1ES only, auto-generated if not specified)
#[serde(default, rename = "service-connection")]
pub service_connection: Option(String),

src/compile/onees.rs uses it to allow overriding the auto-generated service connection name:

let service_connection = opts
    .and_then(|o| o.service_connection.clone())
    .unwrap_or_else(|| format!("mcp-{}-service-connection", name));

The docs explain that 1ES MCPs use service connections and show the auto-generated naming convention (mcp-(name)-service-connection), but never mention that users can override the name. This is especially useful when the ADO service connection was created with a non-standard name.

Suggested Fixes

• In AGENTS.md, change the tools: front matter example from a commented-out RESERVED block to a proper documented field, describing bash and edit sub-options with their semantics (default list, [":*"], [], explicit list, edit: false)
• In AGENTS.md, add documentation for the service-connection: sub-option under the 1ES mcp-servers section, explaining that it overrides the auto-generated mcp-(name)-service-connection naming convention

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷