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

tg-delete-tool

Synopsis

tg-delete-tool [OPTIONS] --id ID

Description

The tg-delete-tool command deletes tools from the TrustGraph system. It removes tool configurations by ID from the agent configuration and updates the tool index accordingly. Once deleted, tools are no longer available for agent use.

This command is useful for:

• Removing obsolete or deprecated tools
• Cleaning up tool configurations
• Managing tool registry maintenance
• Updating tool deployments by removing old versions

The command removes both the tool from the tool index and deletes the complete tool configuration from the TrustGraph API.

Options

• -u, --api-url URL

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

• --id ID

  • Required. Tool ID to delete
  • Must match an existing tool ID in the registry
  • Tool will be completely removed from the system

• -h, --help

  • Show help message and exit

Examples

Basic Tool Deletion

Delete a weather tool:

tg-delete-tool --id weather

Calculator Tool Deletion

Delete a calculator tool:

tg-delete-tool --id calculator

Custom API URL

Delete a tool from a specific TrustGraph instance:

tg-delete-tool --api-url http://trustgraph.example.com:8088/ --id custom-tool

Batch Tool Deletion

Delete multiple tools in a script:

#!/bin/bash
# Delete obsolete tools
tg-delete-tool --id old-search
tg-delete-tool --id deprecated-calc
tg-delete-tool --id unused-tool

Conditional Deletion

Delete a tool only if it exists:

#!/bin/bash
# Check if tool exists before deletion
if tg-show-tools | grep -q "test-tool"; then
    tg-delete-tool --id test-tool
    echo "Tool deleted"
else
    echo "Tool not found"
fi

Deletion Process

The deletion process involves two steps:

1. Index Update: Remove the tool ID from the tool index
2. Configuration Removal: Delete the tool configuration data

Both operations must succeed for the deletion to be complete.

Error Handling

The command handles various error conditions:

• Tool not found: If the specified tool ID doesn't exist
• Missing configuration: If tool is in index but configuration is missing
• API connection errors: If the TrustGraph API is unavailable
• Partial deletion: If index update or configuration removal fails

Common error scenarios:

# Tool not found
tg-delete-tool --id nonexistent-tool
# Output: Tool 'nonexistent-tool' not found in tool index.

# Missing required field
tg-delete-tool
# Output: Exception: Must specify --id for tool to delete

# API connection error
tg-delete-tool --api-url http://invalid-host:8088/ --id tool1
# Output: Exception: [Connection error details]

Verification

The command provides feedback on the deletion process:

• Success: Tool 'tool-id' deleted successfully.
• Not found: Tool 'tool-id' not found in tool index.
• Configuration missing: Tool configuration for 'tool-id' not found.
• Error: Error deleting tool 'tool-id': [error details]

Advanced Usage

Safe Deletion with Verification

Verify tool exists before deletion:

#!/bin/bash
TOOL_ID="weather"

# Check if tool exists
if tg-show-tools | grep -q "^$TOOL_ID:"; then
    echo "Deleting tool: $TOOL_ID"
    tg-delete-tool --id "$TOOL_ID"
    
    # Verify deletion
    if ! tg-show-tools | grep -q "^$TOOL_ID:"; then
        echo "Tool successfully deleted"
    else
        echo "Tool deletion failed"
    fi
else
    echo "Tool $TOOL_ID not found"
fi

Backup Before Deletion

Backup tool configuration before deletion:

#!/bin/bash
TOOL_ID="important-tool"

# Export tool configuration
echo "Backing up tool configuration..."
tg-show-tools | grep -A 20 "^$TOOL_ID:" > "${TOOL_ID}_backup.txt"

# Delete tool
echo "Deleting tool..."
tg-delete-tool --id "$TOOL_ID"

echo "Tool deleted, backup saved to ${TOOL_ID}_backup.txt"

Cleanup Script

Clean up multiple tools based on patterns:

#!/bin/bash
# Delete all test tools
echo "Cleaning up test tools..."

# Get list of test tools
TEST_TOOLS=$(tg-show-tools | grep "^test-" | cut -d: -f1)

for tool in $TEST_TOOLS; do
    echo "Deleting $tool..."
    tg-delete-tool --id "$tool"
done

echo "Cleanup complete"

Environment-Specific Deletion

Delete tools from specific environments:

#!/bin/bash
# Delete development tools from production
export TRUSTGRAPH_URL="http://prod.trustgraph.com:8088/"

DEV_TOOLS=("dev-tool" "debug-tool" "test-helper")

for tool in "${DEV_TOOLS[@]}"; do
    echo "Removing development tool: $tool"
    tg-delete-tool --id "$tool"
done

Integration with Other Commands

With Tool Management

List and delete tools:

# List all tools
tg-show-tools

# Delete specific tool
tg-delete-tool --id unwanted-tool

# Verify deletion
tg-show-tools | grep unwanted-tool

With Configuration Management

Manage tool configurations:

# View current configuration
tg-show-config

# Delete tool
tg-delete-tool --id old-tool

# View updated configuration
tg-show-config

With Agent Workflows

Ensure agents don't use deleted tools:

# Delete tool
tg-delete-tool --id deprecated-tool

# Check agent configuration
tg-show-config | grep deprecated-tool

Best Practices

1. Verification: Always verify tool exists before deletion
2. Backup: Backup important tool configurations before deletion
3. Dependencies: Check for tool dependencies before deletion
4. Testing: Test system functionality after tool deletion
5. Documentation: Document reasons for tool deletion
6. Gradual Removal: Remove tools gradually in production environments
7. Monitoring: Monitor for errors after tool deletion

Troubleshooting

Tool Not Found

If tool deletion reports "not found":

1. Verify the tool ID is correct
2. Check tool exists with tg-show-tools
3. Ensure you're connected to the correct TrustGraph instance
4. Check for case sensitivity in tool ID

Partial Deletion

If deletion partially fails:

1. Check TrustGraph API connectivity
2. Verify API permissions
3. Check for configuration corruption
4. Retry the deletion operation
5. Manual cleanup may be required

Permission Errors

If deletion fails due to permissions:

1. Verify API access credentials
2. Check TrustGraph API permissions
3. Ensure proper authentication
4. Contact system administrator if needed

Recovery

Restore Deleted Tool

If a tool was accidentally deleted:

1. Use backup configuration if available
2. Re-register the tool with tg-set-tool
3. Restore from version control if tool definitions are tracked
4. Contact system administrator for recovery options

Verify System State

After deletion, verify system state:

# Check tool index consistency
tg-show-tools

# Verify no orphaned configurations
tg-show-config | grep "tool\."

# Test agent functionality
tg-invoke-agent --prompt "Test prompt"

Related Commands

• tg-show-tools - Display registered tools
• tg-set-tool - Configure and register tools
• tg-delete-mcp-tool - Delete MCP tools
• tg-show-config - View system configuration

See Also

• TrustGraph Tool Management Guide
• Agent Configuration Documentation
• System Administration Manual