crestapps-core-custom-tools

CrestApps.Core Custom Tools

A code-defined tool is a Microsoft.Extensions.AI AIFunction registered under a name. The orchestrator adds it to requests through the tool registry; the model supplies all its arguments. Use tool instances (crestapps-core-tool-instances) when end users configure the tool, and agents (crestapps-core-ai-agents) when the callable thing is a whole profile.

Guidelines

• Inherit from AIFunction and override Name, Description, JsonSchema and InvokeCoreAsync.
• Register with AddCoreAITool<TTool>(name). Tools are singletons, also registered as keyed AITool services under the name.
• A tool is a system tool by default (hidden from pickers, added by the orchestrator by purpose or context). Call .Selectable() for tools users attach to profiles, and .Hidden() for helper tools only explicitly configured profiles or agents may use; hidden tools stay out of picker and shared MCP listings.
• Catch failures and return a descriptive result the model can act on. Never return null.
• Purpose values are snake case strings (content_generation, not ContentGeneration); always use the AIToolPurposes constants.
• Resolve scoped services from AIFunctionArguments.Services, not from the constructor (the tool is a singleton).
• The deployment must declare toolCalling, or capability enforcement removes every tool from the request.

Registration

builder.Services
    .AddCoreAITool<WeatherTool>(WeatherTool.TheName)
        .WithTitle("Get Weather")
        .WithDescription("Returns current weather for a location.")
        .WithCategory("Utilities")
        .Selectable();