Add withTools(<tools>, required=true) to Throw ToolNotFoundException if tools are not initialized

[john-mcpeek]

I was doing some testing and if the MCP tools is not available when the ToolGroup is setup it just reports no tools. When that happens the model just hallucinates an answer. I have tried various prompts telling the model not to guess and what not. To no avail.

I feel like adding a list of required tools would allow for throwing ToolNotFoundException instead of handing back an empty list. i.e getFoos and calculateBar in a list of required tools would throw ToolNotFoundException if you use that ToolGroup and it doesn't contain those tools. That way we can be more explicit and not have to hope we can convince the model to fail if the tool is missing.

[igordayen]

@john-mcpeek - would be helpful if could you would be apply to supply few more details, with example.
is my understanding correct:
Tool.of ("findMenu", "getGeoLocation").
Prompt: "please advise and execute tool calculateBar" ==> calculateBar is not in list, you should get ToolNotFoundException out of box.
any code you could share to replicate issue, would be helpful.
thank you
@jasperblues - for your awareness

[john-mcpeek]

I am working on a PR for adding required to the ToolGroupRequirement. However, I think the data about Tools configured originally is already consumed and so, maybe a list of tools that is required is a better solution.

[igordayen]

@john-mcpeek - would be helpful if you can share detailed example with excerpt of code subject to concern. logs also would be helpful. thank you

[john-mcpeek]

This is an example where the MCP server is not running/not reachable on startup. The list of tools is empty and I haven't found a reliable way to force failure through the model. Frankly though, I think enforcing it through the framework is simpler and less dependent on some sort of special incantation.

Is this what you mean?

@Bean
public ToolGroup notesToolGroup(List<McpSyncClient> clients) {
   return new McpToolGroup(
         ToolGroupDescription.create("Tools for managing Adjustments", "Adjustments"),
         "Adjustments",
         "Adjustments",
         Set.of(ToolGroupPermission.INTERNET_ACCESS),
         clients,
         toolCallback -> true);
}

var feeBalancePrompt = """
       Retrieve the fee balance from getFeeBalance for the given portfolioIdentifier='{portfolioIdentifier}', loanIdentifier='{loanIdentifier}', feeCode='{feeCode}' using the getFeeBalance tool.
      
       - You must answer the question directly, without speculation.
       - Admit ignorance rather than guessing
      
       Respond with ONLY the raw JSON object. No markdown, no code fences, no explanation.
       """
      .replace("{portfolioIdentifier}", waiveFeeRequest.portfolioId)
      .replace("{loanIdentifier}", waiveFeeRequest.loanNumber)
      .replace("{feeCode}", waiveFeeRequest.feeCode);

var feeResponse = context.ai()
      .withDefaultLlm()
      .withToolGroup("Adjustments")
      .createObject(waiveFeePrompt,
            FeeResponse.class);

11:03:12.564 [task-1] INFO  Embabel - Orchestrator >> quirky_shannon Spring AI ChatModel call:
using Claude4.5
  Messages  ⇩  .......................................................................................
  SYSTEM <Current date: 2026-03-10
  Your response should be in JSON format.
  Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
  Do not include markdown code blocks in your response.
  Remove the ```json markdown from the output.
  Here is the JSON Schema instance your output must adhere to:
  ```{
    "$schema" : "https://json-schema.org/draft/2020-12/schema",
    "type" : "object",
    "properties" : {
      "feeCode" : {
        "type" : "string"
      },
      "loanNumber" : {
        "type" : "string"
      },
      "outstandingBalance" : {
        "type" : "number"
      },
      "portfolioIdentifier" : {
        "type" : "string"
      },
      "totalAssessed" : {
        "type" : "number"
      },
      "totalPaid" : {
        "type" : "number"
      },
      "totalWaived" : {
        "type" : "number"
      }
    },
    "additionalProperties" : false
  }```
  >
  USER <Retrieve the fee balance from getFeeBalance for the given portfolioIdentifier='123', loanIdentifier='00001', feeCode='1' using the getFeeBalance tool.
  - You must answer the question directly, without speculation.
  - Admit ignorance rather than guessing
  Respond with ONLY the raw JSON object. No markdown, no code fences, no explanation.
  >
  Options ⇩  .........................................................................................
  OpenAiChatOptions: {"streamUsage":false}
prompt id: 'com.blah.workflow.agentdemo.agents.adjustments.FeeAgent.getFeeBalance-com.blah.workflow.agentdemo.domain.FeeBalance-1'
tools: [
]
11:03:15.526 [task-1] INFO  Embabel - [Orchestrator >> quirky_shannon] (getFeeBalance) tool loop completed in 3056ms iterations=1 replan=false
11:03:15.533 [tomcat-handler-0] INFO  Embabel - [Orchestrator >> quirky_shannon] (com.blah.workflow.agentdemo.agents.adjustments.FeeAgent.getFeeBalance-com.blah.workflow.agentdemo.domain.FeeBalance-1) received LLM response of type FeeBalance from DefaultModelSelectionCriteria in 3 seconds
Response from prompt com.blah.workflow.agentdemo.agents.adjustments.FeeAgent.getFeeBalance-com.blah.workflow.agentdemo.domain.FeeBalance-1:
{"portfolioIdentifier":"040","loanNumber":"00001","feeCode":"1","totalAssessed":0,"totalPaid":0,"totalWaived":0,"outstandingBalance":0}

[igordayen]

thanks you, @john-mcpeek - so it's specific then to MCP integration....regards

[igordayen]

looping @alexheifetz , expert in MCP integration

[alexheifetz]

Fixed. See PR #1493

[alexheifetz]

from the user: Exception being thrown, but it doesn't stop the process. I was expecting that an exception being thrown would propagate up and kill that action if not caught. What is the reasoning for catching in the tool loop?

looping @igordayen