Manual Creation

Manual Tool Creation gives you complete control over your tool's implementation. While AI-Powered Creation is great for most use cases, manual creation is perfect when you need specific logic, custom optimizations, or integration with existing code patterns.

When to Use Manual Creation

Manual creation is the right choice when you need:

• Full control - You want to write every line of code yourself

• Complex logic - Your tool requires sophisticated business logic that's hard to describe in natural language

• Performance optimization - You need to optimize for specific performance requirements

• Custom patterns - You want to follow specific coding patterns or use particular libraries

• Integration with existing code - You need to reuse existing code or integrate with specific systems

• Fine-tuning - You started with AI generation but need to make significant customizations

• Learning - You want to understand how tools work by writing them yourself

If you're comfortable with JavaScript and want complete control, manual creation is a powerful option. You can also combine approaches - use AI generation to get started, then switch to manual editing for fine-tuning.

Understanding the Tool Function Signature

Every tool in MCP Functions must follow a specific structure. This structure ensures that tools can be called consistently by AI assistants and that they have access to the resources they need.

The Required Function

Every tool must define an async function named execute. This is the entry point that gets called when an AI assistant invokes your tool:

async function execute(params, config) { // params: Object with user-provided parameters // config: Object with workspace secrets (key-value pairs) // Your implementation here return result; }

Understanding the Parameters

The execute function receives two parameters:

1. params (Parameters)

The params object contains all the input data provided by the AI assistant when it calls your tool. The structure of this object matches the parameter schema you define for the tool.

Example: If your tool has parameters "email" (string) and "includeOrders" (boolean), the params object might look like:

{ email: "[email protected]", includeOrders: true }

You access these values in your code using dot notation: params.email or params.includeOrders.

2. config (Configuration)

The config object contains workspace secrets and configuration values. These are the encrypted secrets you stored in your workspace.

Example: If you stored secrets like "STRIPE_API_KEY" and "DATABASE_URL" in your workspace, you can access them like:

const apiKey = config.STRIPE_API_KEY; const dbUrl = config.DATABASE_URL;

Secrets are never exposed in logs, error messages, or code - they're only accessible through the config parameter during execution. If a secret doesn't exist, accessing it will return undefined.

Return Value

Your function should return an object with a standardized structure:

return { success: true, // or false if there was an error data: { // The actual result data // Your data here }, error: "Error message" // Only if success is false };

The return value tells the AI assistant whether the tool execution succeeded and what data was returned. Always return this structure, even when there's an error.

Defining Parameters

Before writing your code, you need to define what parameters your tool accepts. This parameter schema tells AI assistants what inputs to provide when calling your tool.

Parameter Schema Structure

Parameters are defined as a JSON object where each key is a parameter name, and the value describes that parameter:

{ "location": { "type": "string", "description": "City name for weather lookup", "required": true }, "units": { "type": "string", "description": "Temperature units: 'celsius' or 'fahrenheit'", "required": false, "default": "celsius", "enum": ["celsius", "fahrenheit"] } }

Parameter Properties

Each parameter can have the following properties:

• type - The data type: "string", "number", "boolean", "object", or "array"

• description - A clear explanation of what this parameter is for. This helps AI assistants understand when to provide it.

• required - Whether this parameter must be provided (true) or is optional (false)

• default - A default value to use if the parameter is not provided (only for optional parameters)

• enum - A list of allowed values (useful for restricting inputs to specific options)

• format - For strings, can specify formats like "email", "uri", "date-time", etc.

• minimum/maximum - For numbers, can specify min/max values

• minLength/maxLength - For strings, can specify min/max length

Example: Complete Parameter Schema

{ "email": { "type": "string", "description": "Customer email address", "required": true, "format": "email" }, "includeOrders": { "type": "boolean", "description": "Whether to include order history", "required": false, "default": false }, "limit": { "type": "number", "description": "Maximum number of orders to return", "required": false, "default": 10, "minimum": 1, "maximum": 100 } }

This schema defines three parameters: - email - Required string that must be a valid email format - includeOrders - Optional boolean that defaults to false - limit - Optional number between 1 and 100, defaulting to 10

Why Parameter Definitions Matter

Well-defined parameters help AI assistants:

• Understand what data to provide

• Validate inputs before calling your tool

• Provide better error messages if something is wrong

• Use your tool correctly in different contexts

Take time to write clear descriptions and set appropriate validation rules.

Code Structure and Best Practices

Following consistent patterns makes your tools more reliable, maintainable, and easier to debug. Here are the key patterns to follow:

1. Use async/await for Asynchronous Operations

Most tools need to make HTTP requests, access databases, or perform other asynchronous operations. Use async/await for clean, readable code:

async function execute(params, config) { // Good: Using async/await const response = await fetch('https://api.example.com/data'); const data = await response.json(); // Avoid: Callback hell or complex promise chains // fetch('https://api.example.com/data') // .then(response => response.json()) // .then(data => { ... }) }

2. Handle Errors with try-catch

Always wrap your code in try-catch blocks to handle errors gracefully:

async function execute(params, config) { try { // Your code that might throw errors const result = await someOperation(); return { success: true, data: result }; } catch (error) { // Handle the error gracefully return { success: false, error: error.message || 'An unexpected error occurred' }; } }

This ensures that if something goes wrong, your tool returns a proper error response instead of crashing.

3. Validate Input Parameters

Always validate that required parameters are provided and in the correct format:

async function execute(params, config) { // Validate required parameters if (!params.email) { return { success: false, error: 'Email parameter is required' }; } // Validate format if (!params.email.includes('@')) { return { success: false, error: 'Email must be a valid email address' }; } // Continue with your logic... }

Validation helps catch errors early and provides clear error messages to AI assistants.

4. Return Structured Data

Always return data in the standard format:

// Success case return { success: true, data: { // Your actual data here customer: customerData, fetchedAt: new Date().toISOString() } }; // Error case return { success: false, error: 'Clear error message explaining what went wrong' };

This consistent structure makes it easy for AI assistants to understand and use your tool's output.

5. Use console.log for Debugging

You can use console.log to debug your tools. These logs are captured and available in the tool execution logs:

async function execute(params, config) { console.log('Tool execution started with params:', params); // Your code... console.log('Processing result:', result); return { success: true, data: result }; }

Logs help you understand what's happening during execution and debug issues. Be careful not to log sensitive information like passwords or API keys.

6. Access Workspace Secrets Securely

Always access secrets through the config parameter, never hardcode them:

async function execute(params, config) { // Good: Access from config const apiKey = config.API_KEY; if (!apiKey) { return { success: false, error: 'API key not configured in workspace secrets' }; } // Use the API key... }

Always check that secrets exist before using them, and provide clear error messages if they're missing.

Comprehensive Error Handling

Robust error handling is crucial for reliable tools. Your tools will encounter various error conditions, and handling them gracefully ensures a good experience for users.

Basic Error Handling Pattern

Always wrap your code in try-catch blocks:

async function execute(params, config) { try { // Your main code here const result = await performOperation(); return { success: true, data: result }; } catch (error) { // Handle the error return { success: false, error: error.message || 'An unexpected error occurred' }; } }

Handling Specific Error Types

You can handle different types of errors differently:

async function execute(params, config) { try { // Validate inputs first if (!params.email) { return { success: false, error: 'Email parameter is required' }; } // Check for required secrets const apiKey = config.API_KEY; if (!apiKey) { return { success: false, error: 'API key not configured. Please add API_KEY to workspace secrets.' }; } // Make API call const response = await fetch(`https://api.example.com/data?email=${params.email}`, { headers: { 'Authorization': `Bearer ${apiKey}` } }); // Handle HTTP errors if (!response.ok) { if (response.status === 404) { return { success: false, error: 'Customer not found' }; } if (response.status === 401) { return { success: false, error: 'Authentication failed. Please check your API key.' }; } return { success: false, error: `API returned error: ${response.status} ${response.statusText}` }; } const data = await response.json(); return { success: true, data }; } catch (error) { // Handle network errors, timeouts, etc. if (error.name === 'TypeError' && error.message.includes('fetch')) { return { success: false, error: 'Network error: Could not connect to the API' }; } return { success: false, error: `Unexpected error: ${error.message}` }; } }

Error Handling Best Practices

• Validate early - Check inputs and prerequisites before doing expensive operations

• Provide clear error messages - Error messages should explain what went wrong and ideally how to fix it

• Don't expose sensitive information - Never include API keys, passwords, or other secrets in error messages

• Handle expected errors - Anticipate common error conditions (404, 401, network failures) and handle them specifically

• Log errors appropriately - Use console.log for debugging, but be careful not to log sensitive data

Complete Example: A Well-Structured Tool

Here's a complete example that demonstrates all the best practices:

async function execute(params, config) { try { // 1. Validate inputs if (!params.email) { return { success: false, error: 'Email parameter is required' }; } if (!params.email.includes('@')) { return { success: false, error: 'Email must be a valid email address' }; } // 2. Check for required secrets const apiKey = config.CUSTOMER_API_KEY; if (!apiKey) { return { success: false, error: 'CUSTOMER_API_KEY not found in workspace secrets' }; } // 3. Perform the operation const response = await fetch( `https://api.example.com/customers?email=${encodeURIComponent(params.email)}`, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } } ); // 4. Handle HTTP errors if (!response.ok) { if (response.status === 404) { return { success: false, error: `Customer with email ${params.email} not found` }; } return { success: false, error: `API error: ${response.status} ${response.statusText}` }; } // 5. Process the response const customerData = await response.json(); // 6. Return structured success response return { success: true, data: { customer: { name: customerData.name, email: customerData.email, status: customerData.status }, fetchedAt: new Date().toISOString() } }; } catch (error) { // 7. Handle unexpected errors console.error('Unexpected error:', error); return { success: false, error: `An unexpected error occurred: ${error.message}` }; } }

This example demonstrates: - Input validation - Secret checking - HTTP request handling - Error handling for different scenarios - Structured return values - Proper error messages

Testing Your Tools

Before deploying your tool, always test it thoroughly:

• Test with valid inputs - Verify it works with expected data

• Test with invalid inputs - Ensure it handles errors gracefully

• Test with missing parameters - Verify validation works

• Test error scenarios - Simulate API failures, network errors, etc.

• Check return formats - Ensure return values match the expected structure

The platform provides a testing interface where you can run your tools with different inputs and see the results immediately.

Tips for Manual Creation

• Start with AI generation - Even if you plan to write manually, start with AI generation to see a working example, then customize it

• Follow the patterns - Use the patterns shown here for consistency and reliability

• Test frequently - Test your code as you write it, not just at the end

• Use console.log strategically - Log important steps to help with debugging

• Keep it simple - Don't overcomplicate. Simple, clear code is easier to maintain and debug

• Handle all error cases - Think about what can go wrong and handle it

• Document complex logic - Add comments explaining non-obvious parts of your code