Tool and connector engineering
Decide how to expose tools that preserve intent, authority, and recoverable outcomes
When an agent must use enterprise tools with reliable semantics, this area becomes relevant. For the integration engineering lead, the concern is specific: a connector reports success although only part of the requested business change occurred. The engineering design starts from that consequence and follows the relevant evidence through the customer workflow. A tool interface should explain both what an action does and how its outcome is verified. Engineering should distinguish accepted requests, completed effects, partial changes, and failures that can safely be retried.
The engineering decisions relationship
- API specifications
Establish the basis for argument contract.
- Effect confirmation
Distinguish accepted requests from completed business state.
- Tool contract
Retain the scoped finding and its unresolved dependencies.
Decision
Frame the decision around argument contract
Questions and the evidence they need
- Argument contract
- Inspect API specifications for the relevant constraint or observation.
- Effect confirmation
- Inspect action permissions for the relevant constraint or observation.
- Recovery semantics
- Inspect business error semantics for the relevant constraint or observation.
For the integration engineering lead, this becomes relevant when an agent must use enterprise tools with reliable semantics. The immediate decision is how to expose tools that preserve intent, authority, and recoverable outcomes. The scope should be narrow enough that the engineering team can identify a meaningful alternative, including continuing the current approach if the available evidence already supports it.
The practical failure to challenge is that a connector reports success although only part of the requested business change occurred. That concern gives the work a concrete direction: establish what the relevant boundary should do, inspect how it behaves or would operate, and identify the owner of any gap. It should not be diluted into a broad transformation exercise before the specific question has been answered.
Mechanism
Tool contracts should expose partial completion
Relationships within engineering decisions
- Argument contract
- Bind target and action to validated intent.
- Effect confirmation
- Distinguish accepted requests from completed business state.
- Recovery semantics
- Define retry and reconciliation for incomplete operations.
Argument validation
For this scope, argument validation should be examined alongside API specifications. Validate arguments for both schema and business meaning. Entity, unit, date, and scope errors can remain syntactically valid. The proposed connector contract should support clarification or rejection before the agent commits an unintended change to the wrong record.
Effect confirmation
For this scope, effect confirmation should be examined alongside action permissions. Define what each response means about external effects. Accepted, queued, partial, completed, and unknown outcomes need distinct handling where the API exposes them. A tool wrapper should not simplify those states into misleading success or empty data that changes the agent’s decision.
Retry and error interpretation
For this scope, retry and error interpretation should be examined alongside business error semantics. Provide correlation and recovery semantics that let the agent reconcile state before retrying. The design should identify when repetition is safe and when verification or compensation is required. Tests should examine completed business effects, not only whether the connector returned without an exception.
Preparation
Connect the working inputs to the boundary being examined
Evidence packet for argument contract
Illustrative working format
- API specifications
- Identify provenance and the specific decision this material can inform.
- Action permissions
- Specify the subject, operation, resource, and context at the enforcing boundary.
- Business error semantics
- Name the custodian and the conditions requiring a refreshed version.
The starting material is API specifications, action permissions, and business error semantics. Review these together rather than assuming one document tells the whole story. A stated rule may differ from a configured behaviour, and a proposed responsibility may not yet have an available owner. Identify those differences before selecting the detailed work.
Participation should include a workflow owner, an implementation lead, an eventual maintainer, and qualified control reviewers where needed. The customer should define which information and environments may be used. Synthetic or sanitised examples can support preparation when they preserve the relevant behaviour; if they omit a material dependency, record the limitation and agree how the missing evidence would be obtained.
How the work proceeds
Carry argument contract through to an accountable finding
From the scoped material to a decision record
- API specifications
Make the component and operating boundary explicit.
- Effect confirmation
Apply the scoped check to recovery semantics.
- Tool contract
Record the evidence, open dependencies, and the owner’s next decision.
Specify business outcomes alongside schemas. A connector contract should explain whether a response means accepted, completed, partially completed, or unknown, and whether another observation is needed. The proposed implementation should preserve enough correlation to reconcile the external record with the agent’s account of what happened.
A practical first slice would focus on argument validation and then follow its consequences into effect confirmation. Keep retry and error interpretation visible as a separate review question rather than assuming it is satisfied by the first result. The engineering team should record observations, competing explanations, and changes to the original assumptions. A second reviewer can challenge whether the evidence supports the recommendation and whether an apparently successful example omitted the condition that matters most.
Indicative artefact
Make the tool contract usable by its owner
Tool contract
Illustrative working format
- Tool contract
- Record accepted inputs, task meaning, and incomplete or failed outcome semantics.
- Connector implementation backlog
- Name the missing evidence, responsible owner, and condition for revisiting the decision.
- Business outcome test cases
- Name the unresolved condition, next action, and accountable owner.
Indicative outputs include tool contract, connector implementation backlog, and business outcome test cases. Their form should follow the decision and the customer’s existing operating records. The first should establish the assessed boundary and relevant observations; the second should make material gaps or dependencies inspectable; the third should identify the action, owner, and evidence needed to revisit the decision.
Acceptance should be tested through use: can the responsible owner explain what was examined, identify an unresolved issue, and act on the next step without reconstructing the whole engagement? Findings should preserve counterevidence and limits. A polished document is insufficient if it does not help resolve the customer’s specific question.
Illustrative scenario
Examine recovery semantics through a constructed exception
A constructed case and its decision paths
Illustrative scenario
- Argument contract
A case update succeeds while its document attachment fails.
- Effect confirmation
Inspect the case record and attachment result after partial API acceptance.
- Recovery semantics
Reconcile the incomplete effect using the connector's explicit recovery contract.
Consider an illustrative situation in which an agent updates a case and attaches a document through an API that can accept one operation and reject the other. This is a constructed example, not a client engagement or an observed Softlander outcome.
In the case-and-attachment example, a synthetic test would allow record creation to succeed and attachment to fail. The agent should describe partial completion and use the agreed recovery path. The design review would then decide whether the tool contract exposes the state needed for safe continuation rather than encouraging a blind retry.
The useful learning would be the difference between the expected behaviour and the behaviour or responsibility actually demonstrated. If the exercise leaves retry and error interpretation unresolved, that should remain a named next step. A recommendation to narrow the scope, improve a prerequisite, or hold the decision can be appropriate when the example exposes a material dependency.
Scope and next action
Keep the conclusion within the defined workflow and configuration
Confirm fit before the next commitment
- Argument contract
- This review is limited to the defined workflow and configuration.
- API specifications
- The relevant owner must confirm access and the intended operating conditions.
- Tool contract
- Production acceptance needs separate scoped evidence.
The method described here is proposed engineering work. Scope, staffing, implementation access, acceptance, and commercial terms require a readiness review. A design or lab result does not establish production suitability, guaranteed reliability, or security certification.
Ways to engage
Related engagement scopes
AI Fractional Agentic AI Office
Create a regular place for agentic AI decisions. Connect initiative priorities, architecture questions, risk ownership and evidence reviews.
AI Fractional Agentic Transformation Office
Coordinate the operating changes behind agent adoption. Align workflow redesign, ownership, dependencies and adoption measures.
AI Harness Engineering Pod
Engineer a bounded AI execution harness with tool adapters, context handling, orchestration, recovery and observable traces.
Continue exploring
Related insights and resources
Engineer the harness, not just the prompt
Define the contracts around an agent's decisions: what state it trusts, which actions can execute, how interrupted work resumes, and what evidence an operator needs to recover safely.
Governing agent decisions
Governance becomes useful when it changes a decision. Connect each agent workflow to an accountable owner, explicit operating conditions, proportionate evidence and a practical route for exceptions and withdrawal.
Do you need an agent centre of excellence?
A centre can concentrate scarce expertise and reusable controls, or become an approval queue detached from real work. Choose the mandate before the structure.