Patterns

Each tool should expose a focused operation. Reuse application services for data access and business rules rather than repeating those implementations in AI-specific code.

Keep a small tool together

MyApp/
  Agents/
    SupportAgent.cs
  Tools/
    TextStatsTool.cs
  Program.cs

The tool, input record, and output record can share a file while they remain small. Split them into a feature folder when the contract grows.

Attach capabilities with the definition

If Support Agent requires text statistics, attach TextStatsTool in its definition factory. Every caller of that factory then receives the same capabilities.

Use standalone registration when direct tool access is needed without agent attachment. See Attaching tools; avoid duplicating registration blocks throughout startup code.

Inject existing services

A tool can receive repositories, HTTP clients, or other registered services through its public constructor. The runtime creates a new tool instance with ActivatorUtilities; constructor dependencies follow their own registered lifetimes.

Do not keep per-user state in static fields. Check that scoped dependencies are resolved within the appropriate application scope. Registration does not itself prove that a dependency can be resolved; exercise an invocation.

Separate availability from authorization

Attachment determines which tool schemas an agent receives. The tool or application service must still validate the current caller's access and the requested operation.

For write operations, define how duplicate requests, retries, and partial failures are handled. Tool registration does not make a write operation idempotent.

Return useful, bounded results

Return only the fields needed for the task. Bound lists and large responses, and avoid returning credentials or internal diagnostics in tool output.

For expected outcomes, use a structured result that distinguishes success from conditions such as a missing record. Let unexpected failures reach the application's logging and failure handling.

Verify at two levels

Operation: Test known input, invalid values, expected business outcomes, and dependency failures without a model.

Agent integration: Verify selection, arguments, result usage, and final response with the configured model.

The TextStatsTool example provides a deterministic starting point: Hello Runiq yields 11 UTF-16 code units and 2 whitespace-separated words.

Choose the right capability

Use a tool for application operations, RAG for document retrieval, and MCP when compatible external clients need access through that protocol. An agent tool registration does not automatically create an MCP endpoint.