Design tools around narrow customer operations

TL;DR: Give the model tools that express permitted customer operations with bounded inputs and observable results. Keep identity, authorization and effect ownership in the host service, and separate a useful tool response from proof that the overall task succeeded.

Where you are. Northstar's coding workspace is inspectable. You are designing the tool interface shared by its coding and procurement adapters.

Operations a user would recognize

A buyer asks why order N-104 needs review. A good first tool is a scoped policy lookup that returns a document identity, revision, applicable rule and citation. A general-purpose database query tool would hand over far more authority than the question needs, and its result would be harder to validate.

For the coding worker, useful tools might inspect a permitted file, propose a patch and request a named check. For the procurement worker, useful tools might read the current order, retrieve applicable evidence and prepare an amendment. Keep “prepare amendment” separate from “apply approved amendment,” so the model can reason about a proposal without quietly gaining the authority to execute it.

The interface can also be split too finely. A tool that returns one character at a time slows ordinary work and fills the trace with irrelevant calls. Prefer operations that match a meaningful decision, such as retrieving one bounded policy excerpt along with its provenance. Measure the tradeoff on the customer's workload; neither a bare shell nor dozens of tiny tools is better in every case.

Both sides of the contract

For Northstar's read operation:

A tool with no business writes is not automatically harmless. Reading a confidential document, or placing it in a model's context, changes who has access to that information. Apply permission checks before returning content, not after the model has already seen it.

The model does not choose the tenant in this diagram. It supplies the document ID; the host supplies identity. If your real system lets a user select among multiple authorized workspaces, resolve that selection through authenticated membership before constructing the tool context.

Results that support recovery

Tool results should distinguish success, rejection, retryable unavailability and unknown effect status. A timed-out read can often be retried under a bounded policy, but a timed-out amendment may mean the service recorded the change and the response was lost. A generic “tool failed” message for both cases invites unsafe retries.

For writes, include a stable action identity and an authoritative receipt when available. For reads, include source identity and freshness information. A text response saying “done” is too weak to support reconciliation or a later acceptance check.

Keep error explanations short and actionable. “Document unavailable for this operation” tells the worker to look for another authorized source or ask for help; a stack trace containing an access token adds nothing useful. The trace retained for operators can carry a safe error category and correlation ID without exposing credentials to the model.

Do this before moving on

Choose an interface for the following synthetic task: explain whether order N-104 at revision 7 needs buyer review, using policy P-4. The worker may read the order and policy but may not change the order.

Deliverable: specify two read tools, their argument schemas and their success, unavailable and oversized-output results. State where caller identity comes from.

Worked review. read_order(order_id) resolves the order inside the host-authenticated tenant and returns revision, quantity and unit price. read_policy(document_id) returns a current authorized policy excerpt and source identity. Neither takes an admin flag or trusts a model-supplied tenant. No amendment tool is registered in this task's capability set. If policy text exceeds the response budget, the tool offers a bounded retrieval operation rather than clipping the approval condition.

Change the input. The model asks for an amendment tool because it believes reducing the quantity would avoid review. The runtime rejects the unavailable operation before any write. It may still explain the current order. Nothing in the buyer's original question authorized changing the order to make a check pass.

A good tool interface makes the permitted next step easy to express, and it keeps an unauthorized shortcut from being mistaken for ordinary task completion.

Go deeper

• Tool calling: Review the lifecycle of a proposed call and returned observation.
• Identity and authorization: Bind tool access to an authenticated actor rather than generated arguments.
• Tool schema lab: Practice identifying argument shapes that hide ambiguous or excessive effects.

Key takeaways

• Design tools around customer operations and their actual effect boundaries.
• Bind identity in the host and check scope before returning content.
• Return provenance for reads and authoritative effect identity for writes.

Check yourself

Answer before you look. Recalling it is what makes it stick; recognising it does not.

1. 1The task permits only reading an order. The model proposes changing its quantity. What should happen?

   Answer it, then reveal

2. 2Why can a read tool still need a permission check?

   Reads never need permissionReturning confidential content changes who can access informationOnly writes use model context