How to Call Integrations from a Skill Script (gumcp-client)

Your agent can call any connected integration (Gmail, Slack, Google Sheets, Salesforce, etc.) directly from Python scripts inside skills. This is a power-user feature — most tasks don't need it, but it's essential when you need to chain multiple tool calls, process large datasets, or run exact logic that the agent shouldn't improvise.

Why Use Scripts When the Agent Can Call Tools Directly?

Your agent can already call integrations natively — "read my latest emails" or "post to Slack" works without any scripts. For simple, one-off actions, that's the right approach and you don't need this article.

Scripts become valuable when direct tool calls aren't enough. Here's when:

• Chaining multiple calls with logic between them — Read from Sheets → filter → look up owners in Salesforce → send each one a Slack message. A script handles the entire chain in one go.

• Data too large for context — A 1,000-row spreadsheet. With a script, data stays in the sandbox and only the summary enters the agent's context.

• Results must be exactly correct — Commissions, taxes, invoice totals. Python math is deterministic; the agent might approximate.

• Reusable process saved in a skill — "Every Monday, pull Zendesk tickets and post a summary to Slack." Runs identically every time.

• Looping over many items — Enrich 50 contacts, update each CRM record, log results with error handling.

If none of these apply, you probably don't need scripts. Direct tool calls are simpler and work great for most tasks.

How to Think About Scripts as a User

You don't need to write code yourself. Your agent can create skill scripts for you — you just need to describe what the script should do clearly. Think of it like delegating to a developer: the better your brief, the better the result.

One script = one job

Each script in a skill should do one well-defined thing. Don't ask for a mega-script that "handles all our sales operations." Instead, think in terms of discrete tasks:

• A script that reads the sales spreadsheet and computes weekly totals

• A separate script that looks up prospect info from the CRM

• A separate script that formats and posts the weekly summary to Slack

Your skill's SKILL.md instructions can then orchestrate these: "Step 1: Run the totals script. Step 2: Run the Slack summary script." Smaller scripts are easier to debug, easier to reuse, and fail in more predictable ways.

The SKILL.md tells the agent when and why; the script handles how

A common mistake is putting all the logic in the SKILL.md instructions and not using scripts at all. The right split is:

• SKILL.md — Describes the process, decision points, when to run which script, and how to present results to the user

• Scripts — Handle the deterministic work: reading data, doing math, formatting output, calling multiple APIs

The agent handles judgment and context (which deals to include, how to present results). The script handles precision (the actual calculations and API calls).

How to Prompt Your Agent to Create a Script-Based Skill

Good prompt structure

When asking your agent to create a skill with scripts, be specific about:

1. What data to read and from where

2. What to do with it (filter, calculate, transform)

3. Where to send the result (print it, post to Slack, write to a spreadsheet)

4. Which integrations are involved

Example prompts

✅ Good:

"Create a skill called weekly-sales-summary. It should have a script that reads from our Google Sheets spreadsheet (ID: 1ABC...), sums the revenue column, finds the top 3 performers, and prints a formatted summary. The SKILL.md should tell you to run this script whenever I ask for sales numbers, then post the result to #sales in Slack."

✅ Good:

"Create a skill that calculates sales commissions. It should have a script that takes a JSON file of deals as input, applies our tiered commission rates (10% up to $50K, 15% from $50K-$100K, 20% above $100K), and prints a table with each rep's payout. I don't want the agent doing this math itself — it needs to be exact every time."

❌ Too vague:

"Make a skill that handles our sales stuff with scripts."

After the agent creates the skill

Always test it immediately: ask the agent to run the skill and check the output. If something's wrong, tell the agent what to fix — it can update the script in the same conversation. Common follow-ups:

• "The date format is wrong — use MM/DD/YYYY instead."

• "Also include the deal stage in the output."

• "The script is timing out — break it into batches of 100 rows."

Common Gotchas

The integration must be connected to the agent

If your skill's script calls Google Sheets, but Google Sheets isn't connected to the agent, the script will fail at runtime. There's no automatic dependency check — the skill loads fine, but the tool call errors out. Make sure every integration the script uses is added to the agent's Tools panel.

Server IDs aren't the same as display names

In scripts, Google Sheets is gsheets, not google-sheets. Google Calendar is gcalendar, not google-calendar. Your agent knows the correct IDs, but if you're reviewing a script and see an unfamiliar ID, check the reference table at the bottom of this article. You can also ask the agent to run python3 /home/user/skills/gumcp-client/scripts/list_tools.py to see all connected integrations and their IDs.

Scripts run within the sandbox timeout

Python scripts have a 120-second timeout. If your script processes a very large dataset or makes many API calls sequentially, it may time out. Tell the agent to batch the work: "Process 100 rows at a time across multiple script runs" instead of all 5,000 in one go.

Test with a small dataset first

If your script will eventually process hundreds of items, ask the agent to test it with 5 first. This catches field-path errors, missing data, and format issues before you waste a full run. A good prompt: "Run the script on just the first 5 rows to make sure it works before we do the full dataset."

Print output is what the agent sees

Whatever the script print()s is what enters the agent's context. If the script prints nothing, the agent has nothing to work with. If it prints too much (e.g., raw JSON for 500 rows), it floods the context. Design scripts to print summaries, not raw data.

Technical Reference

This section is for users who want to understand or review the code their agent writes.

The basic script pattern

import json, os
from gumcp_client import Client

def get_client():
    return Client(
        user_id=os.getenv('GUMCP_USER_ID'),
        gumcp_api_key=os.getenv('GUMCP_API_KEY'),
        base_url=os.getenv('GUMCP_BASE_URL'),
    )

with get_client() as client:
    result = client.call_tool("server__tool_name", {"arg": "value"})
    data = json.loads(result[0])
    print(data)

Credentials are automatic (pre-set as environment variables). call_tool() takes a tool slug (server__tool_name, double underscore) and an args dict. It returns a list[str] — parse the first element as JSON.

Common server IDs

Run python3 /home/user/skills/gumcp-client/scripts/list_tools.py to see all connected servers and their tools.

Common script errors

Related Docs

• Agent Skills — Calling Integrations From Scripts

• Agent Skills — When to Use Scripts vs. Direct Tool Calls

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.