Class ToolDefinition

java.lang.Object
group.worldstandard.pudel.api.agent.ToolDefinition
public final class ToolDefinition extends Object
Definition of an agent tool.

A tool definition contains all metadata about a tool and its executor. Tools can be created either from @AgentTool annotated methods or programmatically using the builder.

Example using builder: 


ToolDefinition tool = ToolDefinition.builder()
    .name("search_web")
    .description("Search the web for information")
    .parameter("query", String.class, "The search query", true)
    .parameter("limit", Integer.class, "Max results", false)
    .keyword("search")
    .keyword("find")
    .keyword("lookup")
    .executor((context, params) -> {
        String query = (String) params.get("query");
        int limit = (Integer) params.getOrDefault("limit", 5);
        return "Results for: " + query;
    })
    .build();

  • Method Details

    • getName

      public String getName()
      Returns the name of this object.
      Returns:
      the name value

    • getDescription

      public String getDescription()
      Returns the description of this tool definition. The description provides a human-readable explanation of what the tool does and is used by the AI agent to determine when to use this tool.
      Returns:
      the description string

    • getPluginId

      public String getPluginId()
      Returns the unique identifier of the plugin that provides this tool.
      Returns:
      the plugin ID as a String

    • getParameters

      public List<ToolDefinition.ToolParameter> getParameters()
      Returns the list of parameters defined for this tool. Each parameter specifies its name, type, description, whether it is required, and its default value if applicable.
      Returns:
      a list of ToolParameter objects representing the tool's parameters

    • getKeywords

      public Set<String> getKeywords()
      Returns the set of keywords associated with this tool definition. Keywords are used by the AI agent to identify and match user intent when determining which tool to invoke. These keywords help improve the accuracy and relevance of tool selection during agent execution.
      Returns:
      a set of keyword strings associated with this tool

    • isGuildOnly

      public boolean isGuildOnly()
      Indicates whether this tool can only be used within a guild context. When true, the tool is restricted to execution in guild channels only.
      Returns:
      true if the tool requires a guild context, false otherwise

    • isDmOnly

      public boolean isDmOnly()
      Indicates whether this tool can only be used within a direct message context. When true, the tool is restricted to execution in private channels only.
      Returns:
      true if the tool requires a direct message context, false otherwise

    • getPermission

      public AgentTool.ToolPermission getPermission()
      Returns the permission level required to use this tool. The permission level determines which users are allowed to execute the tool based on their role or privileges within the guild or system.
      Returns:
      the required permission level as defined in AgentTool.ToolPermission

    • getPriority

      public int getPriority()
      Returns the priority level assigned to this tool definition. The priority determines the order in which tools are considered when multiple tools match a given request. Higher values indicate higher priority and thus a greater likelihood of being selected.
      Returns:
      the priority level as an integer

    • execute

      public String execute(AgentToolContext context, Map<String,Object> parameters)
      Execute this tool with the given context and parameters.
      Parameters:
      context - the execution context
      parameters - the tool parameters
      Returns:
      the tool result as a string

    • isAvailableIn

      public boolean isAvailableIn(AgentToolContext context)
      Determines if this tool is available for use within the specified execution context. Availability is determined by the tool's configuration for guild-only or DM-only usage. If the tool is configured as guild-only, it will only be available in guild contexts. If configured as DM-only, it will only be available in direct message contexts.
      Parameters:
      context - the execution context in which tool availability is being checked
      Returns:
      true if the tool can be used in the given context, false otherwise

    • builder

      public static ToolDefinition.Builder builder()
      Creates and returns a new instance of the ToolDefinition.Builder class for constructing ToolDefinition instances. The builder provides a fluent API for setting various properties of the tool definition such as name, description, plugin ID, parameters, keywords, context restrictions, permissions, priority, and execution logic.
      Returns:
      a new Builder instance initialized with default values

    • toString

      public String toString()
      Returns a string representation of this ToolDefinition object. The string includes the name, description, plugin ID, and the number of parameters.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the ToolDefinition