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.

Start with the operation a user recognizes

A buyer asks why order N-104 needs review. A useful first tool is a scoped policy lookup. It can return a document identity, revision, applicable rule and citation. A universal database query tool would expose much more authority than this question needs and make the result 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.” That separation lets the model reason about a proposal without silently obtaining the authority to execute it.

Avoid over-fragmenting the interface. A tool that returns one character at a time makes ordinary work slow and fills the trace with irrelevant calls. Prefer operations that correspond to a meaningful decision, such as retrieving one bounded policy excerpt with its provenance. Measure the tradeoff on the customer's workload rather than assuming either a bare shell or dozens of tiny tools is universally better.

Define both sides of the contract

For Northstar's read operation:

The absence of business writes does not make every read harmless. Reading a confidential document or sending it into a model context is an effect on information access. 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.

Return enough information to recover

Tool results should distinguish success, rejection, retryable unavailability and unknown effect status. A timeout on a read can often be retried under a bounded policy. A timeout on an amendment may mean the service recorded the change but its response was lost. Returning the same generic “tool failed” message for both encourages 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 the error explanation actionable and bounded. “Document unavailable for this operation” tells the worker to seek another authorized source or ask for help. A stack trace containing an access token is not more 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. The buyer's original question did not authorize changing the order to make a check pass.

A good tool interface makes the permitted next step easy to express. It also makes an unauthorized shortcut impossible to confuse with 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