Put a typed tool between the model and the system

A model should call a small, typed operation rather than construct arbitrary network requests, database statements or shell commands. The tool translates a business action into a constrained source-system call and validates every argument before using it.

A useful tool definition states:

• the action in plain language;
• required and optional fields with tight types;
• allowed values and maximum lengths;
• the identity and scope checks applied;
• whether it reads, proposes or changes state;
• possible error classes;
• the evidence returned on success.

Keep operations narrow. get_case_summary(case_id) is easier to authorise than query_database(sql). propose_status_change(case_id, target_status, reason) exposes less authority than update_case(payload). Narrow tools also produce clearer evaluation cases because the expected outcome has fewer hidden branches.

Validation should happen outside the model. Confirm identifier formats, permitted transitions, amount bounds, destination domains and current object versions in ordinary code. Reject unknown properties rather than ignoring them. An agent may send an argument that looks plausible but was copied from source material or inferred from an incomplete record.

Return structured errors. Distinguish not_found, not_authorised, ambiguous, conflict, validation_failed, dependency_unavailable and approval_required. A generic error encourages repeated calls and makes it harder to decide whether retry is appropriate.

A tool response should include the source record version or last-modified marker used for the decision. Any later proposal can bind itself to that version. This prevents an approval based on one state from being applied after another person has changed the record.

Keep debug endpoints, unrestricted file readers and raw administration clients under a separate development identity. Add a deployment check that fails if any of them remain in the production tool registry.