Integration Tools

Integration tools are the actions Gondo can use through a connected integration.

A tool might list files, read a document, update a card, create an issue, send an email, or call a custom API endpoint.

Tools and toolsets

Some integrations have a flat list of tools. Others group tools into toolsets.

For example, a Google Workspace integration may expose toolsets such as:

• Drive
• Docs
• Sheets
• Slides

Toolsets make it easier to enable only the parts of a large integration that a workflow needs.

Scopes

Tools have a scope:

An integration can have a maximum scope. If the integration is limited to read, write tools are not available to workflows using that integration.

Disabled tools

Specific tools can be disabled even when their toolset is enabled.

This is useful when an integration has one or two risky actions that a workflow does not need.

For example, a workflow may need to read Drive files and create folders, but not permanently delete files.

Custom tools

Custom API tools are tools created specifically for one connected API integration.

Each custom tool has:

• A name.
• A description.
• A scope.
• An input schema.
• Handler code.

The input schema tells Gondo what arguments the tool accepts. Handler code performs the provider API call through the integration client.

Input schema basics

Tool input schemas use JSON Schema. Keep them small and explicit.

{
  "type": "object",
  "properties": {
    "cardId": { "type": "string" },
    "comment": { "type": "string" }
  },
  "required": ["cardId", "comment"],
  "additionalProperties": false
}

Use required fields for anything the handler must read.

Handler basics

Custom API tool handlers use the connected integration client. Credentials are injected by Gondo, so handler code should not read or store secrets.

async (input) => {
  const response = await integration.post(`/cards/${input.cardId}/actions/comments`, {
    text: input.comment
  })

  const result = await response.json()
  console.log('Added comment to card.')
  return { id: result.id }
}

Provider API calls should go through integration.fetch, integration.get, integration.post, integration.put, integration.patch, or integration.delete.

Good tool design

Good tools are:

• Small.
• Easy to describe.
• Focused on one action.
• Honest about read/write behavior.
• Structured enough that an agent does not need to guess IDs or fields.

For custom integrations, build read or list tools before write tools. This helps workflows discover the correct IDs before changing anything.