SDK built-in tool set differs from the Copilot CLI — `todo` (and others) missing in `.NET` SDK sessions

[NiceAsiv]

Thank you for the SDK and the excellent docs — the custom-agent + skills model has been a pleasure to build on. I ran into a small gap between the documentation and what I observe in the .NET SDK, and I'd love to understand whether it's expected (and, if so, how the docs might be clarified). I may well be misreading the docs, so please correct me if I've misunderstood.

Summary

The reference Custom agents configuration → Tools → Tool aliases enumerates the tool aliases a custom agent's tools: property may contain (execute, read, edit, search, agent, web, todo) and notes the tools property applies to agent profiles "in GitHub.com, the Copilot CLI, and supported IDEs."

When I run the same agent profile through the .NET GitHub.Copilot.SDK (and equivalently via copilot -p), every documented alias resolves to a callable tool except todo / TodoWrite, which appears to resolve to nothing and is silently dropped (consistent with the doc's "All unrecognized tool names are ignored" rule). The net effect is that an agent whose workflow relies on todo can't create the task list — with no error surfaced — so I wasn't sure if this is intended behavior or just something the docs haven't called out yet.

I've included the evidence below in case it's useful; happy to provide more if helpful.

The documented alias table (source of truth)

From https://docs.github.com/en/copilot/reference/custom-agents-configuration#tools:

Alias	Equivalent names	Maps to
execute	shell, Bash, powershell	shell tool
read	Read, NotebookRead	view
edit	Edit, MultiEdit, Write, NotebookEdit	str_replace / editor
search	Grep, Glob	search
agent	custom-agent, Task	custom-agent tools
web	WebSearch, WebFetch	(n/a cloud agent)
todo	TodoWrite	"Creates and manages structured task lists. Not supported in cloud agent today, but supported by VS Code."

The page also says the tools property is valid "in GitHub.com, the Copilot CLI, and supported IDEs," and that "All unrecognized tool names are ignored."

What I observe in the SDK / CLI -p (for reference)

A) CLI -p, default agent — model self-reported available tools (24)

copilot -p "List every tool you currently have available, one name per line, nothing else. Include built-in tools like todo/update_plan if present. Do not call any tool." --allow-all-tools

powershell
write_powershell
read_powershell
stop_powershell
list_powershell
view
create
edit
web_fetch
report_intent
fetch_copilot_cli_documentation
skill
sql
session_store_sql
read_agent
list_agents
write_agent
grep
glob
task
azure-group_list
azure-group_resource_list
azure-kusto
azure-subscription_list
web_search

→ The documented aliases mostly resolve (read→view, edit→edit/create, search→grep/glob, agent→task, execute→powershell*, web→web_fetch/web_search), but there is no tool that todo / TodoWrite resolves to.

B) CLI -p, my custom agent (tools: ["read","search","edit","azure/*","agent","todo","threshold_query"]) — self-reported (10)

view
create
edit
azure-group_list
azure-group_resource_list
azure-kusto
azure-subscription_list
task
skill
report_intent

→ Every documented alias resolves except todo, which is dropped. (grep/glob from search also don't appear under the custom agent in -p.)

C) .NET SDK — GitHub.Copilot.BuiltInTools.Isolated

ask_user
task_complete
exit_plan_mode
task
read_agent
write_agent
list_agents
send_inbox
context_board
skill

→ Also no todo, and this list matches neither the doc's alias table nor the CLI -p set — raising a second question: what is the authoritative built-in surface for SDK sessions?

D) VS Code Copilot — todo is present

In VS Code's "Configure Tools" picker, todo is listed under Built-In: "todo — Manage and track todo items for task planning." So the alias is real and honored in at least one host, consistent with the doc's "supported by VS Code."

E) Observable effect (SDK reasoning trace)

With todo in the allowlist, the model's own chain-of-thought during an SDK run:

"I need to call the task tool to register the five workflow steps as my todo list, though I'm realizing the task tool here launches agents rather than just creating a simple checklist. … I'll take a pragmatic approach: I'll act as the orchestrator running the RCA workflow myself."

The agent correctly distinguishes task (the agent alias — which launches a sub-agent) from todo (a checklist) and gracefully skips the planning step. For completeness I also tried instructing it to "use task to build the todo list," and it (reasonably) declined to repurpose task as a checklist — so substituting task isn't a workaround.

Would any of these help?

1. Clarify the docs: note which hosts honor each alias — e.g. that todo / TodoWrite is VS Code-only today and not available in the Copilot CLI -p / SDK hosts (in addition to cloud agent).
2. Or close the gap: make todo resolvable in SDK / CLI -p sessions, so the documented alias works everywhere the tools property is documented to apply.
3. A per-host built-in tool inventory would be lovely. BuiltInTools.Isolated in the .NET SDK returns 10 names that don't line up with either the CLI -p set or the doc's alias table, so I wasn't sure which list is authoritative for SDK sessions.

Thanks again for taking a look, and for all the work on the SDK — glad to help test any fix or doc change.

Environment

• GitHub.Copilot.SDK 1.0.1 (.NET 8 host)
• Bundled Copilot CLI 1.0.61
• OS: Windows (pwsh)
• Model: claude-opus-4.8
• SessionConfig: EnableConfigDiscovery = true, custom agent selected, one custom tool registered (threshold_query), no AvailableTools / ExcludedTools set.

Repro (minimal)

1. Create a custom agent whose frontmatter tools uses the documented aliases, including todo: tools: ["read","search","edit","agent","todo"].
2. Run it via the .NET SDK (EnableConfigDiscovery=true) or copilot -p --agent <name>; ask the model to list its available tools.
3. Observe: every documented alias resolves except todo, which is silently absent — though the same alias is honored in VS Code per the doc.

[github-actions]

Thanks for the detailed report and the thorough evidence — this is a real documentation gap. Here's a summary of what we've identified:

Documentation Gap Summary

What is missing or unclear

The Custom agents configuration → Tools → Tool aliases reference table does not clearly communicate per-host availability of each alias. Specifically:

1. todo / TodoWrite host scope is understated. The table notes todo is "Not supported in cloud agent today, but supported by VS Code" — but it does not note that todo is also unavailable in the Copilot CLI (-p) and .NET/SDK sessions. The introductory text says the tools property applies "in GitHub.com, the Copilot CLI, and supported IDEs", which implies all aliases work in all those hosts. The reality is that todo silently resolves to nothing outside VS Code.

2. No per-host built-in tool inventory for SDK sessions. GitHub.Copilot.BuiltInTools.Isolated returns 10 names (ask_user, task_complete, exit_plan_mode, task, read_agent, write_agent, list_agents, send_inbox, context_board, skill) that do not correspond to either the CLI -p tool set or the alias table. There is no documentation that explains which tool names are authoritative for SDK-hosted sessions, making it impossible to reason about what tools: filters will actually produce.

Affected documentation

Location	Problem
docs.github.com/en/copilot/reference/custom-agents-configuration#tools — alias table	todo row should note it is VS Code only (not CLI or SDK)
Same page, introductory tools property description	Should clarify that alias support varies by host, not uniform across all
SDK README / reference (Node, .NET, etc.)	Should document the built-in tool surface available in SDK sessions so users understand what tools: filtering yields

Suggested improvements

• Alias table: add a "Hosts" or "Availability" column (or host-specific notes per row) so readers can immediately see that todo is VS Code-only, while execute, read, edit, search, agent, and web are available more broadly.
• SDK docs: add a section listing the built-in tools available in each SDK host context (at minimum, the Isolated set), and explain how the tools: allowlist maps to those names.
• tools property description: add a note that "All unrecognized tool names are silently ignored" applies per-host — so an alias valid in VS Code may resolve to nothing in CLI/SDK, producing no error but also no tool.

The behavior you observed (silent drop, graceful model adaptation) is consistent with the documented "unrecognized names are ignored" rule — but without per-host clarity in the docs it reads as a bug rather than expected behavior. Clarifying this in the reference would set the right expectations and save others the same investigation.

Generated by Documentation Handler for issue #1641 · sonnet46 476K · ◷