openhuman/ai/TOOLS.md

AlphaHuman Tools

This document lists all available tools that AlphaHuman can use to interact with external services and perform actions. Tools are organized by integration and automatically updated during build time.

Overview

AlphaHuman has access to 4 tools across 3 integrations organized into 6 categories.

Quick Statistics:

• Telegram: 2 tools
• Notion: 1 tools
• Gmail: 1 tools

Environment Configuration

Tools are available in different environments with varying capabilities:

Development Environment

Local development environment with full access

• Access Level: Full access to all tools
• Rate Limits: Relaxed for testing
• Authentication: Development credentials
• Logging: Verbose logging enabled

Production Environment

Production environment with security restrictions

• Access Level: Production-safe tools only
• Rate Limits: Standard API limits enforced
• Authentication: Production credentials required
• Logging: Essential logs only

Testing Environment

Testing environment for automated validation

• Access Level: Safe tools for automated testing
• Rate Limits: Testing-specific limits
• Authentication: Test credentials
• Logging: Test execution logs

Tool Categories

Communication

Tools for messaging, email, and social interaction

• Skills: 2
• Tools: 3
• Available Skills: Telegram, Gmail

Productivity

Tools for task management, note-taking, and organization

• Skills: 1
• Tools: 1
• Available Skills: Notion

Available Tools

Gmail Tools

Category: Communication

This skill provides 1 tool for gmail integration.

send_email

Description: Send an email via Gmail

Parameters:

• body (string) (required): Email body content
• subject (string) (required): Email subject line
• to (string) (required): Recipient email address

Usage Context: Available in all environments

Example:

{
  "tool": "send_email",
  "parameters": { "body": "example_body", "subject": "example_subject", "to": "example_to" }
}

---

Notion Tools

Category: Productivity

This skill provides 1 tool for notion integration.

create_page

Description: Create a new page in Notion workspace

Parameters:

• content (array): Page content blocks
• parent_id (string) (required): Parent database or page ID
• title (string) (required): Page title

Usage Context: Available in all environments

Example:

{
  "tool": "create_page",
  "parameters": { "content": [], "parent_id": "example_parent_id", "title": "example_title" }
}

---

Telegram Tools

Category: Communication

This skill provides 2 tools for telegram integration.

send_message

Description: Send a message to a Telegram chat or user

Parameters:

• chat_id (string) (required): Telegram chat ID or username
• message (string) (required): Message text to send
• parse_mode (string): Message formatting mode

Usage Context: Available in all environments

Example:

{
  "tool": "send_message",
  "parameters": {
    "chat_id": "example_chat_id",
    "message": "example_message",
    "parse_mode": "example_parse_mode"
  }
}

---

get_chat_history

Description: Retrieve message history from a Telegram chat

Parameters:

• chat_id (string) (required): Telegram chat ID or username
• limit (number): Number of messages to retrieve

Usage Context: Available in all environments

Example:

{ "tool": "get_chat_history", "parameters": { "chat_id": "example_chat_id", "limit": 10 } }

---

Tool Usage Guidelines

Authentication

• All tools require proper authentication setup through the Skills system
• OAuth credentials are managed securely and refreshed automatically
• API keys are stored encrypted in the application keychain
• Test credentials are available for development and testing environments

Rate Limiting

• Tools automatically respect API rate limits of external services
• Intelligent retry logic handles temporary failures with exponential backoff
• Bulk operations are automatically chunked to avoid hitting limits
• Rate limit status is monitored and reported in real-time

Error Handling

• All tools return structured error responses with detailed information
• Network failures trigger automatic retry with configurable attempts
• Invalid parameters return clear validation messages with examples
• Tool execution timeouts are handled gracefully with partial results

Security & Privacy

• Input validation is performed on all parameters using JSON Schema
• Output sanitization prevents injection attacks and data leakage
• Sensitive data is never logged or exposed in error messages
• All API communications use secure protocols (HTTPS/TLS)

Performance Optimization

• Tool results are cached when appropriate to reduce API calls
• Parallel execution is used for independent operations
• Connection pooling minimizes overhead for repeated API calls
• Background sync keeps data fresh without blocking operations

Monitoring & Observability

• Tool execution metrics are collected for performance analysis
• Error rates and response times are monitored continuously
• Debug logging is available in development environments
• Tool usage analytics help optimize integration performance

Skill Management

Tools are provided by Skills, which are JavaScript modules running in a secure V8 runtime:

• Discovery: Tools are automatically discovered at build time from running skills
• Lifecycle: Skills can be enabled/disabled independently without affecting others
• Configuration: Each skill has its own configuration panel with setup wizards
• Updates: Skills are updated through Git submodules and the Skills management system
• Security: Skills run in sandboxed environments with limited system access

Integration Architecture

V8 Runtime

• Skills execute in isolated V8 JavaScript contexts on desktop platforms
• Mobile platforms use lightweight alternatives with server-side execution
• Memory limits and execution timeouts prevent resource exhaustion
• Inter-skill communication is managed through secure message passing

API Bridge

• Tools communicate with external services through standardized API bridges
• Rate limiting, retry logic, and error handling are implemented at the bridge level
• Authentication tokens are managed centrally and shared across tools
• Response caching and optimization are handled transparently

Data Flow

1. Tool request received from AI agent
2. Input validation and parameter processing
3. Skill execution in secure V8 context
4. API calls through standardized bridges
5. Response processing and formatting
6. Result delivery to AI agent

Support & Troubleshooting

Common Issues

1. Tool Not Available: Check if the associated skill is enabled in Settings → Skills
2. Authentication Errors: Verify credentials in the skill's configuration panel
3. Rate Limit Exceeded: Wait for the limit to reset or upgrade your API plan
4. Invalid Parameters: Review the parameter documentation and examples above

Getting Help

• Skill Documentation: Each skill has detailed setup and usage instructions
• Debug Logs: Enable verbose logging in development mode for detailed error information
• Community Support: Join our Discord community for help from other users
• Technical Support: Contact our support team for critical issues

Contributing

• New Tools: Submit tool requests through our GitHub repository
• Bug Reports: Report issues with specific tools and include error logs
• Improvements: Suggest enhancements to existing tools and their documentation

---

Tool Statistics

• Total Tools: 4
• Active Skills: 3
• Categories: 6
• Last Updated: 2026-03-11T23:23:47.633Z

This file was automatically generated at build time from the V8 skills runtime. For the most up-to-date information, regenerate this file by running yarn tools:generate.