Tools

Tools are the core building blocks of MCP Functions - individual functions that perform specific tasks when called by AI assistants. Understanding how tools work is essential for building effective MCP integrations.

What are MCP Tools?

An MCP Tool is a JavaScript function that performs a specific task when called by an AI assistant. Think of a tool as a function in programming - it takes some inputs (parameters), performs some work, and returns a result.

When a user asks an AI assistant something that requires external action or data, the AI can call your tool to perform that action or fetch that data. For example, if a user asks "What's the weather in New York?", the AI might call a "Get Weather" tool with "New York" as a parameter, receive the weather data, and present it to the user.

An MCP Tool is a JavaScript function that:

• Accepts parameters as input - Tools receive input data through parameters. For example, a "Get Customer" tool might accept a customer email address as a parameter. Parameters are defined with a schema that tells the AI assistant what data to provide.

• Executes in a secure sandbox - Every tool runs in an isolated, secure environment called a sandbox. This means tools can't access other tools' data, can't harm your system, and are limited in what resources they can use. This security is automatic - you don't need to configure it.

• Returns data as output - Tools return results in a structured format. The AI assistant receives this data and can use it to answer the user's question or perform further actions. The return format is standardized so AI assistants know how to interpret it.

• Can make HTTP requests - Tools can call external APIs, fetch data from web services, or interact with other systems over the internet. This is how tools integrate with external services like databases, APIs, or cloud services.

• Can access workspace secrets - Tools can securely access secrets stored in the workspace (like API keys or passwords) through the config parameter. This allows tools to authenticate with external services without hardcoding credentials.

• Can use OAuth2 - Tool config can reference OAuth2 credentials defined at the MCP server level; access tokens are obtained and injected at execution time so tools can call OAuth2-protected APIs.

How Tools Work with AI Assistants

Here's the flow of how tools are used:

• User asks a question - The user asks the AI assistant something that requires external data or action

• AI identifies need for a tool - The AI assistant recognizes that it needs to use a tool to answer the question

• AI calls the tool - The AI assistant calls your tool with the appropriate parameters

• Tool executes - Your tool code runs in a secure sandbox, performs the work, and returns results

• AI uses the results - The AI assistant receives the tool's output and uses it to answer the user's question

This entire process happens automatically. The AI assistant doesn't need to know how your tool works internally - it just needs to know what inputs it takes and what outputs it provides.

Example: A Simple Tool

Let's say you create a tool called "Calculate Square" that calculates the square of a number:

• Parameter: A number (e.g., 15)

• Tool executes: Multiplies the number by itself (15 × 15 = 225)

• Returns: The result (225)

When a user asks "What's 15 squared?", the AI calls your tool with 15, gets back 225, and tells the user "15 squared is 225".

Understanding Tool Structure

Every tool in MCP Functions has a specific structure that defines what it does, what inputs it needs, and how it works. Understanding this structure helps you build better tools.

Every tool consists of:

• Name - A unique identifier for the tool within the MCP server. This is what the AI assistant sees when it discovers available tools. Choose a clear, descriptive name like "get_customer_by_email" or "create_support_ticket". The name should indicate what the tool does.

• Description - A clear explanation of what the tool does. This is crucial - AI assistants use the description to understand when to use your tool. A good description explains:

• What the tool does - When it should be used - What it returns For example: "Fetches customer information from the database using an email address. Returns customer details including name, account status, and order history."

- **Parameters** - The input schema that defines what data the tool needs. Each parameter has:

• A name (e.g., "email", "city", "customerId") - A type (string, number, boolean, object, array) - A description (what this parameter is for) - Whether it's required or optional - Validation rules (e.g., email format, minimum/maximum values) The parameter schema tells the AI assistant what data to provide when calling the tool.

- **Code** - The JavaScript code that actually performs the work. This is where you write the logic for your tool. The code can:

• Process the input parameters - Make HTTP requests to external APIs - Access workspace secrets - Perform calculations or data transformations - Return structured results

- **Status** - Whether the tool is active (available for use) or inactive (disabled but not deleted). You can temporarily disable a tool without deleting it, which is useful for maintenance or testing. - **Config** - Key-value configuration for the tool. Values can be workspace secret references (e.g. `{ source: 'workspace', key: 'API_KEY' }`) or OAuth2 references; both are resolved at execution time so credentials never appear in code. - **Version** - Tools are versioned. Each publish creates a new version; you can view history and roll back to a previous version.

Why Each Component Matters

Each part of the tool structure serves an important purpose:

• Name and Description - Help AI assistants understand what tools are available and when to use them. Without good descriptions, AI assistants might not use your tools correctly or at all.

• Parameters - Define the contract between the AI assistant and your tool. Clear parameter definitions ensure the AI provides the right data in the right format.

• Code - This is where the actual work happens. Well-written code is reliable, handles errors gracefully, and returns useful results.

• Status - Allows you to control tool availability without deleting them. Useful for maintenance, testing, or temporarily disabling problematic tools.

The Tool Function Signature

All tools in MCP Functions must define an execute function with a specific signature. This is the entry point that gets called when an AI assistant invokes your tool.

The standard function signature is:

async function execute(params, config) { // params: User-provided parameters from the AI assistant // config: Workspace secrets and configuration values // Your code here return { success: true, data: {} }; }

Understanding the Parameters

The execute function receives two parameters:

1. params (Parameters)

The params object contains the input data provided by the AI assistant when it calls your tool. The structure of this object matches the parameter schema you defined 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 like 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.

Return Value

Your tool 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. The AI assistant uses this information to continue the conversation with the user.

Complete Example

Here's a complete example of a tool that fetches customer data:

async function execute(params, config) { // Validate input if (!params.email) { return { success: false, error: "Email parameter is required" }; } // Access workspace secret const apiKey = config.CUSTOMER_API_KEY; if (!apiKey) { return { success: false, error: "API key not configured" }; } try { // Make HTTP request const response = await fetch( `https://api.example.com/customers?email=${params.email}`, { headers: { 'Authorization': `Bearer ${apiKey}` } } ); if (!response.ok) { return { success: false, error: `API returned error: ${response.status}` }; } const customerData = await response.json(); // Return success with data return { success: true, data: { customer: customerData, fetchedAt: new Date().toISOString() } }; } catch (error) { return { success: false, error: `Failed to fetch customer: ${error.message}` }; } }

This example shows: - Parameter validation - Accessing workspace secrets - Making HTTP requests - Error handling - Returning structured results

Understanding the Tool Lifecycle

Tools go through a lifecycle from creation to deletion. Understanding each stage helps you manage your tools effectively.

1. Create

Tools are created in one of two ways:

• AI-Powered Creation - Describe what you want in plain English, and the AI generates the complete tool code automatically. This is the fastest way to create tools and works great for most use cases.

• Manual Creation - Write the code yourself for full control. This is useful when you need complex logic, specific optimizations, or integration with existing code libraries.

During creation, you define the tool's name, description, parameters, and code. The tool is created but not yet active.

2. Test

Before deploying a tool, you should test it to ensure it works correctly:

• Validate code - The platform checks that your code is syntactically correct and follows security rules

• Test execution - You can run the tool with sample parameters to see if it produces the expected results

• Check error handling - Test with invalid inputs to ensure the tool handles errors gracefully

• Verify secrets access - Ensure the tool can access required workspace secrets

Testing helps you catch issues before the tool goes live. The platform provides a testing interface where you can run tools with different parameters and see the results.

3. Deploy

Once you're satisfied with testing, you deploy the tool. Deployment is instant - there's no build process or waiting period. The moment you deploy, the tool is:

• Available to AI assistants connected to your MCP server

• Visible in the tool discovery process

• Ready to be called by AI assistants

Deployment is reversible - you can always update or disable the tool later.

4. Update

Tools can be updated at any time:

• Modify code - Update the tool's logic, fix bugs, or add features

• Change parameters - Add, remove, or modify the tool's input parameters

• Update description - Improve the description to help AI assistants understand when to use the tool

• Change status - Activate or deactivate the tool

When you update a tool, the changes are deployed immediately. AI assistants will see the updated tool the next time they discover tools from your server. Version history is maintained, so you can see what changed and when.

5. Delete

When you no longer need a tool, you can delete it:

• Permanent removal - The tool is completely removed from the MCP server

• Immediate effect - AI assistants will no longer see the tool after deletion

• No recovery - Deleted tools cannot be recovered, so be careful. Consider deactivating instead if you might need the tool again.

Before deleting, make sure no AI assistants or other systems are actively using the tool. You can check usage statistics to see if the tool is being used.

Tool Status: Active vs Inactive

Tools have two possible statuses that control their availability:

Active Status

An active tool is:

• Available for execution - AI assistants can see it and call it

• Included in tool discovery - When AI assistants connect to your MCP server, they'll see active tools in the list

• Ready to use - The tool is fully functional and ready to handle requests

Active is the normal state for tools that are in use. When you create and deploy a tool, it's automatically set to active.

Inactive Status

An inactive tool is:

• Disabled but not deleted - The tool still exists, but AI assistants can't use it

• Hidden from discovery - Inactive tools don't appear when AI assistants discover available tools

• Preserved for later - The tool's code and configuration are saved, so you can reactivate it later

Inactive status is useful for:

• Maintenance - Temporarily disable a tool while you fix bugs or update it

• Testing - Disable production tools while testing new versions

• Deprecation - Disable old tools that you're replacing with new ones, but keep them around in case you need to rollback

• Seasonal tools - Disable tools that are only needed at certain times

You can change a tool's status at any time. Deactivating is safer than deleting because you can always reactivate if needed.

Best Practices for Building Tools

• Write clear descriptions - Help AI assistants understand what your tool does and when to use it. Good descriptions lead to better tool usage.

• Validate inputs - Always validate that required parameters are provided and in the correct format. Return clear error messages if validation fails.

• Handle errors gracefully - Use try-catch blocks and return meaningful error messages. Don't let errors crash your tool or return confusing messages.

• Return structured data - Always return data in a consistent format. This makes it easier for AI assistants to use your tool's output.

• Use secrets for credentials - Never hardcode API keys, passwords, or other sensitive data. Always use workspace secrets.

• Keep tools focused - Each tool should do one thing well. If a tool does multiple unrelated things, consider splitting it into multiple tools.

• Test thoroughly - Test with various inputs, including edge cases and error conditions. Make sure your tool handles all scenarios gracefully.

• Document your tools - Write clear descriptions and parameter documentation. This helps both AI assistants and human developers understand your tools.

• Monitor usage - Regularly check which tools are being used and how often. This helps you understand what's valuable and what might need improvement.

• Iterate and improve - Tools can always be improved. Update them based on usage patterns, user feedback, and new requirements.

Common Tool Patterns

Here are some common patterns you'll use when building tools:

Data Fetching Tools

Tools that retrieve data from external sources:

• Fetch customer data from a database

• Get weather information from an API

• Retrieve order history from a system

These tools typically make HTTP requests and return the fetched data.

Data Modification Tools

Tools that create, update, or delete data:

• Create a new support ticket

• Update customer information

• Delete a record

These tools typically make POST, PUT, or DELETE requests and return confirmation of the action.

Calculation Tools

Tools that perform calculations or data transformations:

• Calculate totals or discounts

• Transform data formats

• Perform complex computations

These tools process input data and return calculated results.

Integration Tools

Tools that connect to external services:

• Send emails via SendGrid

• Create calendar events

• Post to Slack channels

These tools use external APIs to perform actions in other systems.

Understanding these patterns helps you design tools that are clear, focused, and easy for AI assistants to use.