Using Custom Tools

Custom tools let you give your agents reusable JavaScript functions for calculations, formatting, data transformation, and other pure logic. This guide walks you through creating, testing, and managing custom tools.

Creating a Custom Tool

Using the AI Wizard

The fastest way to create a tool:

1. Open the Custom Tools view from the left sidebar.
2. Click Create Tool.
3. Describe what you want in plain language:

   "Calculate the compound annual growth rate (CAGR) given a starting value, ending value, and number of years."

4. Pencel generates the tool name, description, input schema, and code.
5. Review the generated code — make sure it handles edge cases (e.g., division by zero, negative years).
6. Click Save.

Writing Code Manually

If you prefer to write the code yourself:

1. Open the Custom Tools view.

2. Click Create Tool.

3. Fill in the fields:

   Name: format_currency

   Description: Format a number as a currency string with the specified currency code.

   Input Schema:

   {
     "type": "object",
     "properties": {
       "amount": { "type": "number", "description": "The amount to format" },
       "currency": { "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR)" }
     },
     "required": ["amount", "currency"]
   }

   Code:

   const symbols = { USD: '$', EUR: '\u20ac', GBP: '\u00a3', JPY: '\u00a5' };
   const symbol = symbols[input.currency] || input.currency + ' ';
   const formatted = input.amount.toLocaleString('en-US', {
     minimumFractionDigits: 2,
     maximumFractionDigits: 2
   });
   return symbol + formatted;

4. Click Save.

Writing Good Tool Descriptions

Your tool's description is how agents decide when to use it. Write descriptions that are:

• Specific — "Format a number as USD/EUR/GBP currency string" is better than "Format stuff."
• Action-oriented — start with a verb: "Calculate," "Convert," "Extract," "Validate."
• Scope-aware — mention what inputs it expects: "Given a start date and end date, calculate the number of business days."

Agents match tool descriptions to the task at hand. A vague description means your tool gets used at the wrong time (or never).

Understanding the Input Schema

The input schema is a JSON Schema that defines what parameters your tool accepts. The agent sees this schema and fills in the values automatically.

Key points:

• Use "required" to mark fields the agent must provide.
• Add "description" to each property — agents read these to understand what to pass.
• Supported types: string, number, boolean, array, object.
• Your code receives the input as a variable called input.

What You Can and Cannot Do

You can:

• Math operations, string manipulation, array/object transformations.
• Use standard JavaScript built-ins (Math, JSON, Array, Object, String, Date, RegExp).
• Return any JSON-serializable value.

You cannot:

• Make network requests (no fetch, XMLHttpRequest).
• Read or write files (no require('fs')).
• Use Node.js APIs (no process, Buffer, child_process).
• Import modules (no require(), no import).
• Run longer than 5 seconds.

WARNING

If your tool needs to access external services or files, it is not a good fit for a custom tool. Use a Connection instead.

Monitoring Your Tools

Usage and Failures

The Custom Tools view shows:

• Usage Count — how many times the tool has been called.
• Failure Count — consecutive failures (resets on success).
• Last Error — the most recent error message.

Auto-Disable

If a tool fails 3 times in a row, Pencel automatically disables it. This prevents broken tools from wasting agent time and tokens.

To fix a disabled tool:

1. Check the Last Error to understand what went wrong.
2. Fix the code.
3. Toggle the status back to Active — this resets the failure count.

Tips

• Keep tools small and focused. One tool should do one thing. A "calculate CAGR" tool is better than a "do all financial calculations" tool.
• Test with simple inputs first. Before using a tool in a workflow, try it in a chat session: ask the agent to use your tool with known inputs and check the output.
• Use descriptive parameter names. startValue is better than sv. Agents are more accurate when parameter names are self-explanatory.
• Handle edge cases in your code. Check for division by zero, empty arrays, and missing optional fields. Return a clear error message instead of crashing.