Tool SDK

16 min read·Updated 30 Jul 2026

Tool SDK is the native extension framework for Arble. Write one implementation and Arble makes it available on desktop, mobile, CLI, API, workflows and agents — no adapters, no per-surface reimplementation.

A tool defined with Tool SDK isn’t a plugin bolted onto one client. It’s registered once into Arble’s tool registry, and every runtime that can call a tool — a desktop session, a scheduled workflow, a remote agent — calls it the same way, with the same schema, the same permission gate and the same audit trail.

Why Tool SDK

MCP gives you a protocol for exposing tools to any compatible client. Tool SDK gives you a runtime built specifically for Arble, and handles everything a tool needs to behave well inside an agent loop rather than just respond to a call.

None of this is scaffolding you opt into later. It’s the shape a Tool SDK tool has from the moment you write @tool.

Quick example

Here’s a complete tool, start to finish:

from arble import tool, Context

@tool(
    name="weather.current",
    description="Get current conditions for a city.",
    permissions=["network.http"],
)
def current_weather(city: str, units: str = "metric", ctx: Context = None) -> dict:
    response = ctx.http.get(
        "https://api.weather.example/v1/current",
        params={"city": city, "units": units},
    )
    response.raise_for_status()
    data = response.json()
    return {
        "city": city,
        "temperature": data["temp"],
        "condition": data["summary"],
        "units": units,
    }

That’s the whole tool. No manifest file, no separate schema definition, no registration step. From this one function, Arble generates:

The function signature is the source of truth. Change a parameter’s type and the schema, validation, generated docs and CLI flags all change with it — there’s nothing else to keep in sync.

Supported languages

Tool SDK ships first-party libraries for four languages. Parity across them is a design constraint, not a roadmap item: the same tool built in any of the four gets the same schema inference, the same streaming model and the same registry entry shape.

Choose based on where the tool needs to run and what it needs to link against — not based on what the SDK supports, because all four support the same surface.

Tool lifecycle

A tool moves through nine stages between being an idea and being something another user’s agent can call.

1. 1DefineWrite the function, its decorator and its docstring.
2. 2RegisterArble reads the decorator and signature into the local registry.
3. 3ValidateThe inferred schema is checked for ambiguity before anything runs.
4. 4TestRun against the test harness with mock resources and permissions.
5. 5PackageCode, dependencies and metadata bundle into a signed artifact.
6. 6PublishPushed to a private, organization or public registry.
7. 7InstallAnother environment pulls the package and its permissions.
8. 8RunThe agent calls the tool like any other registry entry.
9. 9ShareShared directly with a teammate or workflow, scoped by name.

Tool anatomy

Every tool is made of the same nine parts, whether it’s three lines or three hundred.

Input schemas

A tool’s input schema is inferred from its function signature by default. You widen or constrain it with standard typing constructs — Tool SDK doesn’t introduce its own type language.

Primitives — str, int, float, bool — map directly to JSON Schema types. Objects — a dataclass, TypedDict or Pydantic model — become nested schema objects with their own validation. Arrays (list[T]) validate every element, not just the container. Enums (Literal[...]) become a closed set of allowed values. Optional fields follow the parameter’s default — present a default and it’s optional, omit one and it’s required.

from pydantic import BaseModel, Field
from typing import Literal

class CreateIssueInput(BaseModel):
    title: str = Field(..., min_length=1, max_length=256)
    body: str = ""
    labels: list[str] = []
    priority: Literal["low", "medium", "high"] = "medium"
    assignee: str | None = None

@tool(name="github.create_issue", permissions=["network.http"])
def create_issue(input: CreateIssueInput, ctx: Context) -> dict:
    ...

Validation runs before your function body executes. A call with priority="urgent" never reaches your code — the caller gets a schema error naming the exact field and constraint that failed.

Output schemas

Output schemas work the same direction in reverse: Arble validates what your function returns before handing it to the agent, so a tool can’t silently return a shape the caller didn’t ask for.

Typed responses. A return type hint becomes the output schema, the same way input types do. Structured outputs. Nested objects and arrays are validated recursively. Streaming. A streaming tool’s output schema describes the final payload; progress and partial events have their own fixed shape. Resources. A tool can return a resource in place of raw data — the agent gets a reference it can pass to another tool, not a blob to parse.

Errors. Raise a typed exception instead of letting one propagate raw, so the agent can reason about the failure instead of seeing an opaque trace.

from arble import ToolError

class RateLimited(ToolError):
    retryable = True

@tool(name="github.create_issue", permissions=["network.http"])
def create_issue(input: CreateIssueInput, ctx: Context) -> dict:
    response = ctx.http.post("https://api.github.com/issues", json=input.dict())
    if response.status_code == 429:
        raise RateLimited("GitHub rate limit hit, retry after backoff")
    response.raise_for_status()
    return response.json()

Resources

A resource is anything a tool reads or writes that isn’t a plain value — Tool SDK treats these as first-class typed inputs and outputs rather than paths or blobs the tool has to manage itself.

Declaring a parameter as Resource[File] instead of str changes what the agent can pass you: a reference Arble already validated and scoped, not a raw path it has to guess is valid.

Permissions

A tool declares what it needs, not how it will use it. Arble is the one that asks, remembers and enforces — the tool’s code never contains a permission check, because if the function body is running, the permission has already been granted.

@tool(
    name="filesystem.write_report",
    permissions=["filesystem.write:~/Reports"],
)
def write_report(path: str, content: str, ctx: Context) -> dict:
    ctx.fs.write(path, content)
    return {"path": path, "bytes": len(content)}

Grants can be scoped per tool, per workflow or per session, and are inherited down a call chain — a workflow granted network.http doesn’t make a called tool re-prompt, but a tighter scope on the tool is still enforced on top, never loosened by it.

Authentication

Tools that talk to external services need credentials, and Tool SDK resolves them through Arble’s credential store rather than asking you to manage secrets yourself.

Never accept a credential as a plain tool parameter. If a caller can pass it, it can leak into a trace or a workflow definition — resolve credentials through ctx, always.

Streaming

A tool that takes more than an instant should stream, not block. Make the function an async generator and yield instead of returning once.

from arble import tool, Context, Progress

@tool(name="repo.clone", permissions=["filesystem.write", "network.http"])
async def clone_repository(url: str, dest: str, ctx: Context):
    yield Progress(message="Resolving repository", percent=0)

    async for received, total in ctx.git.clone(url, dest):
        yield Progress(
            message=f"Receiving objects ({received}/{total})",
            percent=int(received / total * 100),
        )

    yield {"path": dest, "commit": await ctx.git.head(dest)}

Progress updates carry a message and an optional percent, and render as a live status line without polling. Partial outputs let a tool yield pieces of its result as they’re ready. Long-running tasks stay attached to the same call rather than needing a separate status check — the stream is the status. Cancellation arrives on ctx.cancelled, checked cooperatively between yields. Timeouts are enforced by Arble regardless of whether the tool checks cancellation.

Development

arble dev runs a local loop built around fast iteration on a single tool.

Hot reload. Saving the tool file re-registers it within milliseconds. Inspector. A live panel showing the current schema, the last five calls and any validation errors as you type. Schema viewer. Renders the generated JSON Schema exactly as the registry stores it. Permission preview. Shows the exact prompt a user sees on first call. Logs. Structured, per-call logs filterable by tool. Registry. A local-only view matching the shape of the production registry. CLI. Every capability above is also a scriptable command — arble tools inspect, arble tools schema, arble tools logs.

Testing

Tool SDK’s test harness runs a tool without a live Arble session, so tests are fast and don’t depend on network state or a real agent loop.

Unit testing. arble.testing.call(tool, **kwargs) invokes a tool directly against its schema. Mock tools. Any tool your tool calls internally can be swapped for a mock. Replay. Record a real call once and replay it in CI without hitting the live service again. Snapshots. Assert that a tool’s output schema hasn’t changed unexpectedly. Permission simulation. Run a tool as though a permission were denied. Failure simulation. Inject a timeout or malformed response to verify error handling.

from arble.testing import call, deny_permission

def test_create_issue_success():
    result = call(create_issue, input=CreateIssueInput(title="Bug"))
    assert result["title"] == "Bug"

def test_create_issue_without_network_permission():
    with deny_permission("network.http"):
        with pytest.raises(PermissionError):
            call(create_issue, input=CreateIssueInput(title="Bug"))

Publishing

arble tools publish pushes a packaged tool to a registry. Which registry depends on who should be able to install it.

Versioning. Tools follow semantic versioning. A published version is immutable — a fix ships as a new version, never an overwrite. Signing. Every package is signed with the publisher’s key; Arble refuses an unsigned or tampered package on install.

Built-in helpers

ctx gives every tool access to a set of helpers so common operations don’t require a new dependency or a hand-rolled client.

Example tools

Each of these is a normal Tool SDK tool — nothing about them is privileged or built with a different API than the one described on this page.

Tool registry

Every tool Arble can call — regardless of where it came from — lands in one registry, indexed the same way.

The planner that decides which tool to call for a given step reads name, description, input schema and permission requirements — the same four fields regardless of source. Adding a source of tools never means teaching the planner something new, and a tool you publish through Tool SDK is chosen exactly as readily as one Arble shipped with. See MCP server for how connectors join the same registry.

Performance

Cold start. A tool’s first call in a session pays a one-time cost to load its code and resolve permissions; every call after reuses the warm instance. Caching. Declare a result as cacheable with a TTL — @tool(cache_ttl=60) — and repeated identical calls are served from cache. Streaming. Lets Arble start planning the next step before the current one fully completes, when the plan doesn’t depend on the final value. Memory. Write summaries, not raw payloads — a dumped API response bloats every future context that reads it back. Latency. The registry tracks p50/p95 per tool and surfaces regressions before a user reports them. Retries. Mark errors retryable=True and Arble retries with backoff automatically. Timeouts. Set a tool-level default with @tool(timeout=30); callers can request a shorter deadline, never a longer one.

Security

Best practices

1. Keep a tool’s scope narrow — one clear job, not a dozen optional modes.
2. Name tools namespace.action (github.create_issue), so the registry stays legible at scale.
3. Write the docstring for the agent, not for yourself — it’s what the planner reads.
4. Declare the narrowest permission that works, scoped to specific paths or hosts.
5. Never accept credentials as parameters — resolve them through ctx.secrets or ctx.auth.
6. Prefer typed models over loose dict parameters — the schema is only as good as the types.
7. Stream anything that takes more than a couple of seconds.
8. Check ctx.cancelled between yields in any streaming tool.
9. Raise typed ToolError subclasses instead of letting exceptions propagate raw.
10. Mark genuinely retryable errors retryable=True, never ones that write data non-idempotently.
11. Write memory entries as summaries, not raw dumps.
12. Version deliberately — a breaking schema change is a major version, not a patch.
13. Test with permission simulation, not just happy-path calls.
14. Return resources instead of raw paths or blobs for files, images or documents.
15. Keep the function body free of permission or credential checks — that’s what the decorator is for.

Reference

• Decorators — @tool, parameters, defaults
• Schemas — type inference rules, explicit overrides
• Resources — full resource type catalog and helpers
• Permissions — scope syntax, grant levels, inheritance
• Streaming — Progress, partial results, cancellation
• Memory — read/write API, retention, summarization
• Authentication — ctx.secrets, ctx.auth, OAuth setup
• CLI — full arble tools command reference
• Publishing — package format, signing, registry configuration
• Testing — arble.testing API reference
• API — REST and streaming endpoints for published tools

FAQ