[stippi]

ToolRegistry kept its tools in a HashMap, so they reached the model in an order that differed for every new registry. The registry is rebuilt at the start of each agent run, and tools come first in the prefix prompt caches key on. A changed order would therefore miss the cache on a run's first request. I read this from the code and did not measure it. The same randomness is why test_tool_use_docs_generation only failed now and then (fixed in #298).

The order now

• Registry: tools is an IndexMap, so tools stay in registration order. Replacing a tool or adding a capability tag does not move it.
• Built-in tools: register_default_tools registers them by topic: finding and reading, changing files, running commands, the web and browser, the agent's own work, earlier sessions, skills. ask_question follows where it is offered.
• MCP tools: after the built-ins, server by server. This code did not need changing: servers come in config order (a BTreeMap, so alphabetical by name) and each server's tools as list_tools returns them.
• Toggles and per-session switches: these stay filters on top and leave the remaining tools in order.

The xml and caret tool docs follow the same order, since they read the same definitions.

Testing

• New tests cover registration order across a replacement, a tag and a filter, the built-ins' order by topic, identical order from two registries, and an MCP server's tools in its listed order. The registry test failed before the change.
• cargo test --workspace, clippy with -D warnings, the format check and cargo deny check pass locally.
• Prompt-cache hit rates were not checked against a real provider.

The first request after this ships sees a new tool order once, so it misses the cache as usual after any prompt change.