How to Make Tool Usage Conditional Based on Context in an LLM Agent

[whobutsb]

Hey! I’m building an Agent that reviews Jira tickets and helps flesh out details. I’m passing in the ticket data programmatically as context for the chat session. Sometimes there’s a linked Confluence page, and I’d like the Agent to pull that in if it’s available.

The issue is that the Agent is always trying to use the Confluence tool, even when no URL is present in the context.

My question: how do I make the tool usage conditional—only if a Confluence URL is found? Should this logic be handled in the tool’s description, or is there a better way to indicate optional use?

Example Tool Class:

class GetConfluencePage extends Tool
{
    public function __construct()
    {
        parent::__construct(
            'get_confluence_document',
            'If a Confluence wiki link is available retrieve a Confluence document by its ID',
        );
        $this->addProperty(
            new ToolProperty(
                name: 'document_id',
                description: 'The ID of the Confluence document to retrieve',
                type: 'string',
                required: true,
            )
        )->setCallable(function(string $document_id): string {
            Log::info("Retrieving Confluence document with ID: $document_id");
            $doc = (new Confluence)->getPage($document_id);
            $response = "### {$doc['title']} - {$doc['url']}\n\n{$doc['content']}";
            return $response;
        });
    }
}

[ilvalerione]

What AI provider are you using?

[ilvalerione]

If the "document_id" property is required, how can the model call the tool without this information? It should fire an exception.

[whobutsb]

Yeah that is understood. Maybe I'm mis-understanding how tools are supposed to be used, are they optional augmentation for the AI to use? Where it would make the decision to use the tool if it has the required parameters? Or does the AI always try to call the tool regardless if it can provide the parameter ie - document_id?

[ilvalerione]

Yes, they are optional things the model can decide to use. It is entirely at the discretion of the LLM. How do you know the agent "always" call the tool? Do you have the Inspector tracing enabled?

[whobutsb]

I could tell it was always calling because it get erroring out with the exception of a missing parameter (document_id). I actually did some additional reading on MCP servers and was reviewing how the descriptions were written. I have updated my descriptions so that they are more descriptive and that has seemed to fix the problem. Being more explicit with what the tool does and how it should be used does the trick.

Example:

    public function __construct()
    {
        parent::__construct(
            'get_confluence_document',
            'This tool retrieves a Confluence document by its ID. It returns the document title, URL, and content in a markdown format. This is useful for providing additional context or information related to a Jira ticket or other tasks that require reference to Confluence documentation. Example url: https://company.atlassian.com/wiki/spaces/SPACE/pages/123456/Document+Title',
        );
        $this->addProperty(
            new ToolProperty(
                name: 'document_id',
                description: 'The ID of the Confluence document to retrieve, such as "123456" or "789012". This should be the unique identifier for the Confluence page you want to access. You can find this ID in the URL of the page or by using the Confluence API.',
                type: 'string',
                required: true,
            )
        )->setCallable(function(string $document_id): string {
            Log::info("Retrieving Confluence document with ID: $document_id");
            $doc = (new Confluence)->getPage($document_id);
            $response = "### {$doc['title']} - {$doc['url']}\n\n{$doc['content']}";
            return $response;
        });
    }

[ilvalerione]

Never underestimate prompt engineering.

[whobutsb]

Tell me about it. Probably the most difficult part about creating Agents. Appreciate the conversation, really enjoying the library. Looking forward to seeing where it goes!