Zio.Tools

Mail sending, reputation lookup, file downloading, and other tools registered on the screen are invoked within a skill. A skill cannot directly call /tools/ — that path is blocked from where the skill runs, and the only gateway to data is the SDK. Zio.tools passes through that gate instead. It shows its ID and only allows tools that are in the allowlist.

Do not swallow failures. If a tool fails, this function throws an exception — let it propagate so the skill ends in failure. Previously, when /tools/ was called directly and blocked, we swallowed the failure with try/except, producing a “false success,” leaving the node marked as successful without storing any result.

The arguments for each tool follow its specification—check the agent builder’s tool list. Within a skill you can see what is usable via Zio.tools.list().

from zio_ontology import Zio

# 스킬에서 부를 수 있는 도구 목록
for t in Zio.tools.list():
    print(t["tool_id"], t["method"])

# 메일 발송 (인자는 그 도구의 규격을 따른다)
Zio.tools.execute("send_email_via_smtp", {
    "to_email": "hong@example.com",
    "subject": "주간 업무 확인 요청",
    "body": "<p>확인 부탁드립니다.</p>",   # 본문은 이미 완성된 것을 넘긴다
})

# 도메인 평판 조회 — 결과(dict)를 그대로 돌려받는다
whois = Zio.tools.execute("analyze_domain", {"domain_name": "example.com"})
print(whois.get("is_registered"), whois.get("domain_age_days"))

# 파일 다운로드 — 바이너리는 bytes 로 온다
pdf_bytes = Zio.tools.execute("gdrive_download_file", {"file_id": "1AbC..."})
open("/tmp/spec.pdf", "wb").write(pdf_bytes)

Method	Description
Zio.tools.list()	List of tools that can be called from a skill. Returns [{tool_id, method}]. Tools not listed here cannot be invoked — raw tools such as shell, file, or raw query are not exposed to skills.
Zio.tools.execute(tool_id, args)	Invoke a single tool. tool_id is the name of the tool; args is a dictionary of arguments that the tool accepts. On success it returns the result provided by the tool (usually a dict), and for binary outputs such as file downloads it returns bytes.

Tools that cannot be called are blocked with guidance

A tool_id not in the allowlist is blocked with a PermissionError, and the error message includes the list of callable tools. Shell execution, file read/write, and raw queries cannot be invoked from a skill — if you need those capabilities, use the proper SDK interface. Do not call /tools/ manually.

The role of a tool differs from that of a skill

Zio.tools is an entry point for invoking already‑registered tools. Reading and writing data is handled by Zio.code, Zio.node, Zio.entity, and Zio.ingestion — those are the official channels through which a skill interacts with data.

Creating Tools — External REST API and Remote MCP Registration

If you don’t have the necessary tool, create it yourself. Two types can be registered: an external REST API (like Postman where “you call this address in this way”), and a remote MCP server (like DeepWiki·Context7 that attaches to an MCP via URL). Once registered, the agent’s model will invoke them on its own (LLM tool calling) — REST uses arguments according to the params specification, MCP fills in action and arguments.

v1 creates restapi and remote HTTP MCP. The local stdio MCP·skill is a boundary that launches a process; it’s still only for the web admin, and custom_script is unimplemented.

A created tool starts as a draft (useYN='N') — a person can preview it in the web ToolBuilder and enable it. Tools are shared across the entire instance, so this review gate is important.

Security: The actual calls to tools you create run from an isolated location (skillnet), so they reach external addresses but cannot access internal services (neo4j·redis, etc.). If you put an internal address in url, it won’t work (that’s how it was designed).

from zio_ontology import Zio

# 바깥 REST API 를 도구로 등록 (초안으로 생성)
got = Zio.tools.create(
    title="날씨 조회",
    url="https://api.weather.com/v1/current?city={{city}}",
    method="GET",
    headers={"X-API-Key": "..."},
    params=[
        {"key": "city", "type": "string", "required": True,
         "description": "조회할 도시명"},
    ])
print(got["id"], got["tool_id"])   # -> 53 weather_...
print(got["warnings"])             # 이상하면 여기 담긴다 — 꼭 읽는다

# 한 도구의 전체 설정 보기 (id 또는 tool_id 로)
Zio.tools.get(got["tool_id"])

# 고치기 (안 준 것은 유지, tool_id 는 안 바뀐다)
Zio.tools.update(got["id"], description="도시별 현재 날씨")

# ── 원격 MCP 서버 등록 (DeepWiki·Context7 처럼 URL 로 붙는 MCP) ──
mcp = Zio.tools.create(
    title="내 위키",
    type="mcp",
    url="https://mcp.deepwiki.com/mcp",   # 원격 HTTP MCP 서버 주소
    transport="http")                     # "http"(Streamable) 또는 "sse"
# 모델은 실행 시 action_name(예: ask_question) + JSON 인자로 호출합니다.
# 로컬 실행(command 방식) MCP 는 SDK 로 못 만듭니다 — 원격 HTTP MCP 만.

# 지우기 (사용자가 만든 것만 — 시스템 도구는 거부)
Zio.tools.delete(got["id"])

# 이제 웹 도구 빌더에서 열어 프리뷰 → 활성화(켜기)

Method	Description
Zio.tools.create(title, url, ...)	Registers a tool (draft). restapi (default): method·headers·auth· params·body·response_schema, where params is the LLM input contract ({key,type,required,description,default}), and {{var}} automatically becomes an argument. mcp (type="mcp"): url·transport (http/sse) — only remote HTTP MCP (local stdio is web‑admin only). Returns {id, tool_id, warnings}.
Zio.tools.get(ref)	Retrieves the full configuration of a single tool (input params, authentication, body, etc.). ref can be an id or tool_id.
Zio.tools.update(ref, ...)	Replaces settings for an existing user tool. Unchanged fields are preserved; tool_id (name) is immutable. System tools are rejected.
Zio.tools.delete(ref)	Deletes a user tool (system tools are rejected).

System Tools vs My Tools

The system tools that are provided to all users cannot be created or modified by the SDK (they can only be read and called). A tool created with create is an own (user) tool, and update/delete apply only to user tools. View the list with Zio.tools.list().