Tools and Capability Boundaries

A tool is an application-controlled capability offered to a model through a name, description, argument schema, and handler. Good tools are narrow, typed, tenant-scoped, observable, cancellable, and explicit about side effects. Tool access is delegated authority; adding a tool changes the system’s threat model, not merely its feature list.

What will you be able to do?

You will replace broad capabilities with domain tools, classify risk, and specify the controls required before a tool can execute.

What is the mental model?

A tool schema is a door label. The handler and policy are the lock. A label that says “employees only” does not stop entry; a prompt that says “use carefully” does not enforce authorization.

What makes a good tool contract?

Compare two designs:

text

Bad:  run_sql(query: string) -> string
Good: get_ticket(ticket_id: Ticket
Id, tenant_id from trusted context) -> Ticket
View

The first lets the model invent query text and scope. The second exposes one business capability and obtains tenant identity from authenticated runtime context.

Define every tool with:

purpose and non-purpose;
typed arguments and bounded strings/lists;
data classification and tenant scope;
read-only, mutating, destructive, idempotent, and open-world annotations;
required permission and approval level;
timeout, concurrency, and retry ownership;
sanitized result schema;
audit and redaction policy; and
reconciliation behavior after uncertain failure.

How do you implement a safe read tool?

python

from dataclasses import dataclass


@dataclass(frozen=True)
class RequestContext:
    tenant_id: str
    actor_id: str


async def get_ticket(context: RequestContext, ticket_id: str) -> dict[str, str]:
    if not ticket_id.startswith("T-"):
        raise ValueError("ticket_id must start with T-")
    row = await repository.get_ticket(context.tenant_id, ticket_id)
    if row is None:
        raise LookupError("ticket not found in tenant scope")
    return {"id": row.id, "subject": row.subject, "status": row.status}

The model supplies ticket_id. Trusted host code supplies tenant_id. The result excludes internal notes and customer secrets.

How do mutating tools differ?

A mutating tool needs a stronger contract:

text

propose_ticket_update(...) -> ProposedChange       # read/compute
approve_change(proposal_id, approver) -> Decision  # human/policy
apply_ticket_update(proposal_id, idempotency_key)  # mutation
verify_ticket_update(proposal_id) -> Evidence      # reconciliation

Separating proposal from commit makes review and replay explicit.

Failure injection: Make the external update succeed, then drop the network response. On retry, the same idempotency key must return the prior outcome or reconcile it; it must not apply the change twice.

How do you prove a tool is safe enough?

Test that unauthorized tenants, invalid schemas, denied permissions, expired approvals, timeouts, duplicate idempotency keys, redaction, and result-size limits behave correctly without invoking a model. Then run agent-level tests for correct selection and arguments.

What mistakes should you avoid?

Exposing shell, SQL, or HTTP when a domain tool would suffice.
Taking identity, tenant, or permission from model arguments.
Returning full records when three fields are enough.
Retrying a mutation at the HTTP client, tool, and worker layers.
Trusting tool annotations as the security decision themselves.

Check your understanding

Why does adding a tool change the threat model?
Which arguments must come from trusted context?
How does proposal/commit separation improve safety?

Expert extension

Write a policy matrix for five SupportOps tools. Include risk, data class, auto-allow conditions, approval role, timeout, idempotency, and audit fields.

Official references

Tools and Capability Boundaries

What makes a good tool contract?

Compare two designs:

text

Bad:  run_sql(query: string) -> string
Good: get_ticket(ticket_id: Ticket
Id, tenant_id from trusted context) -> Ticket
View

The first lets the model invent query text and scope. The second exposes one business capability and obtains tenant identity from authenticated runtime context.

Define every tool with:

purpose and non-purpose;

typed arguments and bounded strings/lists;

data classification and tenant scope;

read-only, mutating, destructive, idempotent, and open-world annotations;

required permission and approval level;

timeout, concurrency, and retry ownership;

sanitized result schema;

audit and redaction policy; and

reconciliation behavior after uncertain failure.

How do you implement a safe read tool?

python

from dataclasses import dataclass


@dataclass(frozen=True)
class RequestContext:
    tenant_id: str
    actor_id: str


async def get_ticket(context: RequestContext, ticket_id: str) -> dict[str, str]:
    if not ticket_id.startswith("T-"):
        raise ValueError("ticket_id must start with T-")
    row = await repository.get_ticket(context.tenant_id, ticket_id)
    if row is None:
        raise LookupError("ticket not found in tenant scope")
    return {"id": row.id, "subject": row.subject, "status": row.status}

The model supplies ticket_id. Trusted host code supplies tenant_id. The result excludes internal notes and customer secrets.

How do mutating tools differ?

A mutating tool needs a stronger contract:

text

propose_ticket_update(...) -> ProposedChange       # read/compute
approve_change(proposal_id, approver) -> Decision  # human/policy
apply_ticket_update(proposal_id, idempotency_key)  # mutation
verify_ticket_update(proposal_id) -> Evidence      # reconciliation

Separating proposal from commit makes review and replay explicit.

Failure injection: Make the external update succeed, then drop the network response. On retry, the same idempotency key must return the prior outcome or reconcile it; it must not apply the change twice.

What mistakes should you avoid?

Exposing shell, SQL, or HTTP when a domain tool would suffice.

Taking identity, tenant, or permission from model arguments.

Returning full records when three fields are enough.

Retrying a mutation at the HTTP client, tool, and worker layers.

Trusting tool annotations as the security decision themselves.