Tools are what allow Zoho Zia Agents to move beyond answering questions and take real actions in your business systems. With tools connected, an agent can retrieve records, update statuses, send communications, and interact with external APIs. Without tools, an agent can only reason and respond; with them, it can act.

Tool Categories

System Tools

System tools are pre-built and organised by Zoho service, including CRM, Desk, Campaigns, and Books. They require no configuration and are immediately available to add to any agent.

Custom Tools

Custom tools cover APIs that are not included in the system tool library. They are defined using YAML files in OpenAPI 3.0 format and allow you to integrate with specialist, third-party, or internal services.

Understanding API Basics

Each tool is based on an API call, which has two core parts:

• Method: Defines the type of action. GET retrieves data, POST creates records, PUT updates them, and DELETE removes them.
• Endpoint: Specifies where the action targets, often including dynamic parameters such as {record_id}.

For example, GET /crm/v8/Leads/{record_id} instructs the agent to retrieve a specific lead's details from Zoho CRM.

YAML Configuration for Custom Tools

Custom tool YAML files must follow the OpenAPI 3.0 specification and include the following sections:

• Metadata: Specification version, title, and description.
• Server and security: Base URL and authentication method, typically OAuth2 with the required scopes listed.
• Endpoints (paths): API routes with HTTP methods, summaries, descriptions, and unique operationIds for each action.
• Parameters: Input specifications including where they appear (path, query, or header), whether they are required, and their data types.
• Responses: Expected HTTP status codes for both success and failure outcomes.
• Security schemes: Full OAuth2 configuration details.

Creating a Custom Tool: Step by Step

1. Open Tools. Navigate to the Tools section and click + New Tool Group.
2. Name the group. Enter a descriptive name and an optional description.
3. Upload the schema. Click + Add Schema and upload your YAML file (maximum 500 KB).
4. Validate. Click Validate to review the parsed tools and check for errors.
5. Test. Select the tools you want to test and click Test All Tools.
6. Connect. Associate a connection with the tool group (using an existing connection, creating a new one, or allowing one to be auto-created).
7. Verify scopes. Use the info button to check that the OAuth scopes match what the API requires.
8. Enter test values. Fill in real values for any mandatory parameters.
9. Run the test. Execute the test and review the results.
10. Mark as ready. Flag tools that passed testing as production-ready.
11. Save. Confirm and save the configuration.

Best Practices

• Group related tools that address a specific workflow into a single tool group.
• Request only the permissions your tools actually need; avoid broad access scopes.
• Use clear, unambiguous names for both groups and individual tools.
• Always test with sample data before marking tools as ready for production use.
• Re-validate tools after any updates to the underlying API service to avoid silent failures.