Tools Guide

Extend agents with native catalog entries, custom uploads, and BOSA connectors. Use this guide when you need to attach bespoke logic, integrate vendor connectors, or govern tool reuploads across environments via REST, the Python SDK, or the CLI.

Check tooling coverage in the AIP capability matrix. Today the CLI lacks inline edits for metadata, tool configs, and runtime overrides—use export/import or the SDK/REST when you need those controls. Platform-managed BOSA connectors remain partially gated behind operations enablement.

Create Tools

Python SDK

from glaip_sdk import Client

client = Client()

# Upload a custom Python tool from disk
tool = client.create_tool(
    name="calculator",
    file_path="./calculator.py",
    description="Performs basic arithmetic",
    tags=["math", "demo"],
)

print(tool.id)

CLI

REST

Tool Source Expectations

• Python tools must export a tool_plugin decorated function or class.

• Dependencies are packaged inside the upload (zip or single file).

• Runtime stdout/stderr is captured and forwarded in the agent event stream.

# calculator.py
from typing import Any

from gllm_plugin.tools import tool_plugin
from langchain_core.tools import BaseTool
from pydantic import BaseModel, Field


class CalculatorArgs(BaseModel):
    expression: str = Field(..., description="Arithmetic expression to evaluate")


@tool_plugin(version="1.0.0")
class CalculatorTool(BaseTool):
    name = "calculator"
    description = "Evaluates simple arithmetic expressions."
    args_schema = CalculatorArgs

    def _run(self, expression: str, **_: Any) -> str:
        # Replace with business-safe evaluation logic
        return str(eval(expression, {"__builtins__": {}}, {}))

The full calculator.py example above mirrors the structure used in python/glaip-sdk/hello_tool.py and the SDK examples. Update the _run implementation to call your own business logic instead of eval before uploading.

Manage Tools

Update or Re-upload

CLI re-uploads replace the code package; adjust metadata by editing an export and re-importing or by using the SDK/REST helpers.

Python SDK

client.update_tool_via_file(tool_id, "./calculator_v2.py")
client.tools.update_tool(tool_id, description="Adds percentage support")

CLI

REST

Delete

Python SDK

client.tools.delete_tool("tool-id")

CLI

REST

Common errors and fixes

Symptom	Likely cause	Fix
422 Unprocessable Entity on upload	Missing tool_plugin decorator or invalid metadata fields.	Validate the module exports tool_plugin and double-check required metadata (name, version, description).
CLI upload hangs after progress bar	Large dependency bundle or slow network upload.	Zip the tool directory, remove unused assets, or upload via the REST API with a resumable client.
Agent cannot run the tool at runtime	Tool not attached, or config missing required keys.	Re-run aip agents update --tools and verify tool_configs in the agent payload.
401 Unauthorized when calling /tools endpoints	API key scoped to viewer-only role.	Request a creator or runner key, or perform the action via an operator account.

Attach Tools to Agents

Python SDK

agent = client.agents.create_agent(
    name="math-helper",
    instruction="Use the calculator tool for arithmetic",
    tools=[tool.id],
    tool_configs={
        tool.id: {"precision": 2}
    },
)

CLI

REST

Persist tool-level configuration in the agent payload under tool_configs. Use aip agents get --export to edit and re-import while CLI flags are still in development.

CLI placeholders such as TOOL_REF accept either the tool ID or a unique name. For partial matches, use --select or supply the ID directly, especially inside scripts.

BOSA and Managed Connectors

Platform-managed connectors (BOSA library) appear in the tool catalog with predefined IDs. Request enablement from the AIP operations team, then attach them like any other tool. Updates are handled centrally; monitor the changelog for new versions.

MCP Tool Discovery

# List tools exposed by an MCP configuration
curl -sL "$AIP_API_URL/mcps/<MCP_ID>/tools" \
  -H "X-API-Key: $AIP_API_KEY" | jq

Use the response to seed agent definitions or generate tool uploads where appropriate. The MCP guide covers credential rotation and live connection testing in detail.

Observability and Auditing

• GET /tools/<id> returns metadata, version, and upload timestamps.

• GET /agents?tools=<id> surfaces reuse across agents.

• Leverage the Configuration management guide to export/import tools alongside agents for promotion pipelines.

Best Practices

1

Version your uploads

Keep source code in git and re-upload on change.

2

Scope permissions

Custom tools run with the same rights as the agent execution environment; follow least-privilege principles.

3

Validate inputs

Handle argument validation inside the tool to avoid unexpected failures mid-run.

4

Document configs

Record supported configuration keys in your README so teammates know how to set tool_configs.

Related Documentation

• Agents guide — attach tools, manage tool_configs, and run overrides.

• File processing — upload artifacts during agent runs and reuse chunk IDs.

• Automation & scripting — script tool creation and promotion in CI.