trustgraph/docs/cli/tg-set-tool.md

tg-set-tool

Synopsis

tg-set-tool [OPTIONS] --id ID --name NAME --type TYPE --description DESCRIPTION [--argument ARG...]

Description

The tg-set-tool command configures and registers tools in the TrustGraph system. It allows defining tool metadata including ID, name, description, type, and argument specifications. Tools are stored in the agent configuration and indexed for discovery and execution.

This command is useful for:

• Registering new tools for agent use
• Updating existing tool configurations
• Defining tool arguments and parameter types
• Managing the tool registry for agent workflows

The command updates both the tool index and stores the complete tool configuration in the TrustGraph API.

Options

• -u, --api-url URL

  • TrustGraph API URL for configuration storage
  • Default: http://localhost:8088/ (or TRUSTGRAPH_URL environment variable)
  • Should point to a running TrustGraph API instance

• --id ID

  • Required. Unique identifier for the tool
  • Used to reference the tool in configurations and agent workflows
  • Must be unique within the tool registry

• --name NAME

  • Required. Tool name used by agents to invoke this tool
  • Must be a valid function identifier (use snake_case, no spaces or special characters)
  • Examples: get_weather, calculate_distance, search_documents

• --type TYPE

  • Required. Tool type defining its functionality
  • Valid types:
    • knowledge-query - Query knowledge bases
    • text-completion - Text completion/generation
    • mcp-tool - Model Control Protocol tool

• --description DESCRIPTION

  • Required. Detailed description of what the tool does
  • Used by agents to understand tool capabilities
  • Should clearly explain the tool's purpose and function

• --argument ARG

  • Tool argument specification in format: name:type:description
  • Can be specified multiple times for multiple arguments
  • Valid argument types:
    • string - String/text parameter
    • number - Numeric parameter

• -h, --help

  • Show help message and exit

Examples

Basic Tool Registration

Register a simple weather lookup tool:

tg-set-tool --id weather_tool --name get_weather \
            --type knowledge-query \
            --description "Get current weather information" \
            --argument location:string:"Location to query" \
            --argument units:string:"Temperature units (C/F)"

Calculator Tool

Register a calculator tool with MCP type:

tg-set-tool --id calc_tool --name calculate \
            --type mcp-tool \
            --description "Perform mathematical calculations" \
            --argument expression:string:"Mathematical expression to evaluate"

Text Completion Tool

Register a text completion tool:

tg-set-tool --id text_gen_tool --name generate_text \
            --type text-completion \
            --description "Generate text based on prompts" \
            --argument prompt:string:"Text prompt for generation" \
            --argument max_tokens:number:"Maximum tokens to generate"

Custom API URL

Register a tool with custom API endpoint:

tg-set-tool -u http://trustgraph.example.com:8088/ \
            --id custom_tool --name custom_search \
            --type knowledge-query \
            --description "Custom tool functionality"

Tool Without Arguments

Register a simple tool with no arguments:

tg-set-tool --id status_tool --name check_status \
            --type knowledge-query \
            --description "Check system status"

Tool Types

knowledge-query

Tools that query knowledge bases, databases, or information systems:

• Used for information retrieval
• Typically return structured data or search results
• Examples: web search, document lookup, database queries

text-completion

Tools that generate or complete text:

• Used for text generation tasks
• Process prompts and return generated content
• Examples: language models, text generators, summarizers

mcp-tool

Model Control Protocol tools:

• Standardized tool interface for AI models
• Support complex interactions and state management
• Examples: external API integrations, complex workflows

Argument Types

string

Text or string parameters:

• Accept any text input
• Used for queries, prompts, identifiers
• Should include clear description of expected format

number

Numeric parameters:

• Accept integer or floating-point values
• Used for limits, thresholds, quantities
• Should specify valid ranges when applicable

Configuration Storage

The tool configuration is stored in two parts:

1. Tool Index (agent.tool-index)

   • List of all registered tool IDs
   • Updated to include new tools
   • Used for tool discovery

2. Tool Configuration (agent.tool.{id})

   • Complete tool definition as JSON
   • Includes metadata and argument specifications
   • Used for tool execution and validation

Advanced Usage

Updating Existing Tools

Update an existing tool configuration:

# Update tool description
tg-set-tool --id weather --name "Weather Lookup" \
            --type knowledge-query \
            --description "Updated weather information service" \
            --argument location:string:"Location to query"

Batch Tool Registration

Register multiple tools in a script:

#!/bin/bash
# Register a suite of tools
tg-set-tool --id search --name "Web Search" --type knowledge-query \
            --description "Search the web" \
            --argument query:string:"Search query"

tg-set-tool --id summarize --name "Text Summarizer" --type text-completion \
            --description "Summarize text content" \
            --argument text:string:"Text to summarize"

tg-set-tool --id translate --name "Translator" --type mcp-tool \
            --description "Translate text between languages" \
            --argument text:string:"Text to translate" \
            --argument target_lang:string:"Target language"

Tool Validation

Verify tool registration:

# Register tool and verify
tg-set-tool --id test-tool --name "Test Tool" \
            --type knowledge-query \
            --description "Test tool for validation"

# Check if tool was registered
tg-show-tools | grep test-tool

Error Handling

The command handles various error conditions:

• Missing required arguments: All required fields must be provided
• Invalid tool types: Only valid types are accepted
• Invalid argument format: Arguments must follow name:type:description format
• API connection errors: If the TrustGraph API is unavailable
• Configuration errors: If tool data cannot be stored

Common error scenarios:

# Missing required field
tg-set-tool --id tool1 --name "Tool 1"
# Output: Exception: Must specify --type for tool

# Invalid tool type
tg-set-tool --id tool1 --name "Tool 1" --type invalid-type
# Output: Exception: Type must be one of: knowledge-query, text-completion, mcp-tool

# Invalid argument format
tg-set-tool --id tool1 --name "Tool 1" --type knowledge-query \
            --argument "bad-format"
# Output: Exception: Arguments should be form name:type:description

Integration with Other Commands

With Tool Management

View registered tools:

# Register tool
tg-set-tool --id new-tool --name "New Tool" \
            --type knowledge-query \
            --description "Newly registered tool"

# View all tools
tg-show-tools

With Agent Invocation

Use registered tools with agents:

# Register tool
tg-set-tool --id weather --name "Weather" \
            --type knowledge-query \
            --description "Weather lookup"

# Use tool in agent workflow
tg-invoke-agent --prompt "What's the weather in London?"

With Flow Configuration

Tools can be used in flow configurations:

# Register tool for flow use
tg-set-tool --id data-processor --name "Data Processor" \
            --type mcp-tool \
            --description "Process data in flows"

# View flows that might use the tool
tg-show-flows

Best Practices

1. Clear Naming: Use descriptive, unique tool IDs and names
2. Detailed Descriptions: Provide comprehensive tool descriptions
3. Argument Documentation: Clearly describe each argument's purpose
4. Type Selection: Choose appropriate tool types for functionality
5. Validation: Test tools after registration
6. Version Management: Track tool configuration changes
7. Documentation: Document custom tools and their usage

Troubleshooting

Tool Not Appearing

If a registered tool doesn't appear in listings:

1. Verify the tool was registered successfully
2. Check the tool index with tg-show-tools
3. Ensure the API URL is correct
4. Verify TrustGraph API is running

Tool Registration Errors

If tool registration fails:

1. Check all required arguments are provided
2. Verify argument format is correct
3. Ensure tool type is valid
4. Check API connectivity
5. Review error messages for specific issues

Tool Configuration Issues

If tools aren't working as expected:

1. Verify tool arguments are correctly specified
2. Check tool type matches intended functionality
3. Ensure tool implementation is available
4. Review agent logs for tool execution errors

Related Commands

• tg-show-tools - Display registered tools
• tg-delete-tool - Remove tool configurations
• tg-set-mcp-tool - Configure MCP tools
• tg-invoke-agent - Use tools with agents

See Also

• TrustGraph Tool Development Guide
• Agent Configuration Documentation
• MCP Tool Integration Guide