Builders

Toolsets and agents declare themselves in their constructors, and this page lists every call they can make. To learn the calls in context, read Toolsets, Tool settings and Agents.

Rules for every chain

The generator reads each chain from your source at compile time, and at runtime the calls only record values. Because the generator reads source, put every declaration directly in the constructor (TSH014) and write it as one chain in one statement (TSH015). Names, descriptions, the storage kind and the schema version must be constants (TSH002). Each toolset derives from Toolset and each agent from Agent directly (TSH017).

Toolset

Call	Does
`WithDisplayName(string displayName)`	Names the toolset for people, for example in a tool picker. `DisplayName` reads it back.
`AddTool(Delegate method)`	Declares a tool backed by a static method group, such as `AddTool(SearchTickets)`, and returns its `ToolBuilder`. For a lambda, an instance method or a local function, the analyzer reports TSH003.

Toolsets explains a tool's name and description, its parameters, including those the call fills instead of the model, and the results it may return.

ToolBuilder

Call	Does
`WithName(string name)`	Replaces the name derived from the method. It must be lower_snake_case (TSH008).
`WithDescription(string description)`	Replaces the `<summary>`. For a tool with neither, the analyzer reports TSH009.
`RequiresApproval()`	Makes the tool's calls need approval. Unless a rule, a standing approval or auto mode decides a call, the run ends, and the call runs once your app approves it in the conversation's next run. See Approval and modes.
`ReadOnly()`	Marks a tool that only reads and changes nothing. Plan mode offers only these.
`WithSettings<TSettings>()`	Gives the tool a settings record that stays in code, except the members `Configurable` names. Returns `ToolBuilder<TSettings>`.
`WithConfigurableSettings<TSettings>()`	Gives the tool a settings record whose settable members may all change, except those `NotConfigurable` names. Returns `ConfigurableSettingsBuilder<TSettings>`.

Put the settings call last in the tool's chain, because it returns ToolBuilder<TSettings> or ConfigurableSettingsBuilder<TSettings>, which offer only the calls below: ReadOnly() after it is a compiler error (CS1061). TSettings is a record whose parameterless constructor sets the code defaults (TSH005), and the tool's method takes a parameter of that type (TSH010).

Configurable members

Call	On	Does
`Configurable(s => s.Member)`	`ToolBuilder<TSettings>`	Lets the member change at runtime, through stored settings or a run.
`NotConfigurable(s => s.Member)`	`ConfigurableSettingsBuilder<TSettings>`	Keeps the member in code.

The generator reads these lambdas and never runs them, so each one must name a member directly, as in s => s.Member (TSH015). A configurable member needs a public set or init accessor (TSH013) and a type that settings can store (TSH012); Tool settings lists those types. WithConfigurableSettings leaves members marked [Obsolete] out without a NotConfigurable call.

Agent

Call	Does
`WithName(string name)`	Names the agent, which is otherwise its class name in snake_case. Messages the agent writes carry the name as their author.
`WithDescription(string description)`	Says what the agent does. A sub-agent or a handoff target needs one (TSH023).
`WithStorageKind(string kind)`	Sets the kind a store keys the agent's `Settings` by, in place of its class name, so renaming the class keeps its stored settings.
`WithSchemaVersion(int version)`	Sets the schema version of the stored `Settings`, 1 unless raised. Raise it after you rename or remove a configurable member, so you can migrate older documents.
`WithChatOptions()`	Returns the `ChatOptionsBuilder`.
`WithRunOptions()`	Returns the `RunOptionsBuilder`.
`UseToolset<TToolset>()`	Offers every tool of the toolset. `.Include(t => t.X)` offers only the tools picked, in that order, and `.Exclude(t => t.X)` all but those. One use includes or excludes, never both. Use each toolset once and pick each tool once (TSH025).
`AddTool(Delegate method)`	Declares a tool of the agent's own, backed by a static method of the agent, and returns its `ToolBuilder`. The agent offers it after the tools of its toolsets. See Agents.
`UseAgent<TAgent>()`	Offers another agent as a tool named like it, with one `input` parameter. `.InBackground()` returns at once and delivers the answer later. See Sub-agents.
`UseHandoff<TAgent>()`	Offers a tool `handoff_to_{name}` that hands the conversation to the other agent. See Handoff.
`UseMcpServer(string server)`	Offers the tools of an MCP server that your app's `IMcpToolProvider` connects. `.RequiresApproval()` makes every call to its tools wait for approval, and `.ReadOnly()` lets plan mode offer them.
`UseContext<TProvider>()`	Adds what an `IContextProvider` returns to every run. The run's services resolve the provider, or create it when none is registered.

The agent's instructions come from GetInstructions(), a virtual method you override. Typeshift calls it each time it resolves a run's options, so it runs for every run.

ChatOptionsBuilder

WithChatOptions() sets the chat options every run starts from. Configurable(o => o.X) lets stored settings or a run change an option, even one the code never sets, and makes it a member of the agent's Settings. An option with "No" in the last column cannot be configurable (TSH012): it belongs to the run, as the tools do, or settings cannot store its type.

Call	Sets	May be configurable
`WithModel(TProviderId provider, string model)`	`ModelId`, and the provider that serves it	Yes, as `Provider` and `Model`
`GetInstructions()`, overridden in the agent	`Instructions`	Yes
`WithTemperature(float temperature)`	`Temperature`	Yes
`WithMaxOutputTokens(int tokens)`	`MaxOutputTokens`	Yes
`WithTopP(float topP)`	`TopP`	Yes
`WithTopK(int topK)`	`TopK`	Yes
`WithFrequencyPenalty(float penalty)`	`FrequencyPenalty`	Yes
`WithPresencePenalty(float penalty)`	`PresencePenalty`	Yes
`WithSeed(long seed)`	`Seed`	Yes
`WithStopSequences(params string[] sequences)`	`StopSequences`	Yes
`WithAllowMultipleToolCalls(bool allow)`	`AllowMultipleToolCalls`	Yes
`WithReasoning(ReasoningOptions reasoning)`	`Reasoning`	Yes
`WithResponseFormat(ChatResponseFormat format)`	`ResponseFormat`	No
`WithToolMode(ChatToolMode mode)`	`ToolMode`	No
`WithTools(params AITool[] tools)`	Adds tools of no toolset to `Tools`, such as a `HostedWebSearchTool` or a function from `AIFunctionFactory`	No
`WithAdditionalProperty<TValue>(string key, TValue value)`	A provider-specific option in `AdditionalProperties`	No

RunOptionsBuilder

WithRunOptions() sets how a run goes: its mode, the limits of its tool loop and when its history is compacted. Every run option may be configurable: Configurable(r => r.X) puts it into the agent's Settings, like a chat option.

Call	Default	Does
`WithMode(AgentMode mode)`	`Default`	Sets the mode runs start in: `Default`, `Plan` or `Auto`.
`WithMaxToolIterations(int iterations)`	40	Sets the most rounds of tool calls one run makes. Calls your app approves run in the next run, which counts its own.
`WithMaxConsecutiveToolErrors(int errors)`	3	Sets how many rounds of tool calls in a row may fail before the failing tool's exception ends the run and reaches your code.
`WithConcurrentToolCalls(bool concurrent)`	off	Runs the tool calls in one model response at the same time.
`WithMaxInputTokens(int tokens)`	off	Turns compaction on at this many input tokens.
`WithTargetInputTokens(int tokens)`	half the maximum	Sets how far compaction shrinks the history.
`WithSummaryModel(string model)`	the run's model	Sets the model that summarizes the oldest turns when clearing old tool results does not shrink the history enough, served by the run's provider. Made configurable, it also adds `SummaryProvider` to `Settings` (the summary model).

Toolsets: declaring tools, and their names, parameters and results.
Tool settings: settings records and their configurable members.
Agents: declaring an agent and choosing its tools.
Generated members: what the generator writes from these chains.
Diagnostics: what the analyzer reports when a chain breaks a rule.

Builders ​

Rules for every chain ​

Toolset ​

ToolBuilder ​

Configurable members ​

Agent ​

ChatOptionsBuilder ​

RunOptionsBuilder ​

Related ​