Tools and integrations
Understand how tools and integrations relate to credentials, MCP, approvals, and failure handling without inventing unsupported contracts.
Tools and integrations
Tools and integrations connect model-centered work to operations beyond a direct response. Use this page to identify what must be verified before an agent or workflow reads from, writes to, or acts on another system. The repository recognizes MCP, approvals, policies, environment configuration, and tool-oriented validation concepts, but Batch 01 does not define every connector, contract, credential flow, or failure mode.
Tools
A tool is a callable operation made available to a product, agent, or workflow. It should have a bounded purpose and a defined contract. A useful tool description answers:
- What operation does the tool perform?
- Which inputs are accepted?
- Which outputs or artifacts are returned?
- Does it read state, propose a change, or execute a change?
- Which model or agent may call it?
- What configuration or credential is required?
- Which evidence is recorded?
Without those details, the correct wording is “tool concept” or “planned operation,” not “supported tool.”
Tools should not be treated as model capabilities. A code-capable model can draft a command without having permission to run it. A model can explain an API without possessing a configured integration. Execution depends on the surrounding product and control plane.
Tools are concrete operations exposed to supported agent or workflow surfaces. A tool should be documented by its purpose, inputs, outputs, side effects, permissions, and failure behavior.
The inspected sources do not supply those detailed contracts. Use the term to explain the platform model and defer exact tool documentation to the product that owns the operation.
Integrations
An integration is the configured relationship between Ethen and another service, data source, or runtime. It can expose one or more tools, but an integration may also provide context, credentials, events, or destination settings.
Integration readiness has multiple layers:
| Layer | Verification question |
|---|---|
| Presence | Does the owning product list the integration? |
| Configuration | Is the endpoint, provider, or connection configured? |
| Authentication | Is the required credential present and valid? |
| Authorization | May the current actor use the integration? |
| Capability | Does it support the intended read or write operation? |
| Approval | Has the specific state-changing action been authorized? |
| Verification | Is there evidence that the target system accepted the action? |
A failure at one layer should not be described as a failure of the entire platform. Identify the layer and preserve the visible evidence.
An integration connects Ethen to another system or source so supported work can read data or prepare actions.
The shell recognizes integration-related areas such as MCP and environment variables, but route recognition does not prove a connector, credential flow, or live action. Do not list provider names or supported systems without direct evidence.
Integration inventory
Maintain an inventory that separates recognized integrations from configured ones. For each entry, record the owning product, purpose, current state, credential owner, supported operations, approval requirement, and evidence path. Leave unsupported fields blank rather than completing them from expectation.
An inventory can also show dependencies. A workflow may require a provider credential, an MCP connection, and a target-system permission. Seeing those prerequisites together prevents a team from calling the workflow ready merely because one connection succeeded.
Credentials
Credentials are secrets or configuration items required to access providers and integrations. The model catalog includes a missing-key status for provider access, and the approved Gateway route map includes an API-key area. This does not establish the exact creation, storage, rotation, revocation, or inheritance process.
Operational rules for documentation and testing:
- Never place real credentials in prompts, screenshots, examples, or generated artifacts.
- Refer to the current product’s credential control rather than inventing environment-variable names.
- Distinguish a missing credential from an invalid credential or unsupported operation.
- Verify which workspace, project, provider, or integration receives the configuration.
- Do not claim encryption, secret isolation, rotation policy, or compliance behavior without an authoritative source.
If a tool reports an authentication failure, capture the status and target integration, then use the owning product’s supported remediation path.
Credentials authorize access to a provider or connected system. AI Gateway exposes an approved API-key route, and Model Library can report missing-key status.
This batch does not define storage, encryption, rotation, sharing, or scope. Never include secrets in examples. Use the product-specific credential guide before configuring production access.
MCP
MCP is recognized by the shell as a platform concept, but the current bundle does not verify server implementations, supported transports, discovery, tool schemas, authentication, lifecycle, or product coverage.
At this stage, MCP can be discussed as a possible boundary through which tools or context are exposed. A complete MCP guide would need to verify:
- which Ethen product acts as client or host;
- how servers are added and identified;
- what tools, resources, or prompts are exposed;
- how credentials are handled;
- how approval and policy apply;
- what happens when a server is unavailable;
- which receipts or logs are produced.
Do not substitute general MCP knowledge for those product facts. Direct routes and setup instructions belong to the later batch after implementation inspection.
MCP is a recognized platform route and concept, but the current product surfaces do not define supported transports, server configuration, resources, tools, authentication, or lifecycle.
Describe MCP only as an integration mechanism that requires separate product evidence. Do not invent configuration files, commands, or compatibility claims.
Approvals
Approvals separate a proposed external effect from execution. They are most important for tools that write data, send messages, create resources, alter configuration, or trigger another system.
A reviewable approval packet should make the proposed action legible:
- target system and object;
- action type;
- inputs or changes;
- context used to prepare the proposal;
- expected result;
- known risk or irreversible effect;
- evidence that will confirm completion.
The current sources support the approval-path concept but not universal UI labels, role names, expiration rules, or multi-approver behavior. Avoid describing those details until the owning product verifies them.
Approval does not correct a missing credential, unsupported modality, invalid tool input, or unavailable target. It authorizes an action that must still pass runtime validation.
Approvals separate a visible proposed action from supported state-changing execution.
Do not assume that every tool call requires approval or that every surface has the same approval UI. Exact triggers, approver authority, rejection behavior, and audit events must be verified from later sources.
Failure behavior
Tool and integration failures should be classified before they are retried.
| Failure class | Example signal | Appropriate response |
|---|---|---|
| Discovery | Tool or integration is not present | Verify product support; do not invent a route |
| Configuration | Provider or endpoint is not configured | Complete the supported setup or choose another path |
| Authentication | Key or credential is missing | Use the verified credential process; keep secrets out of prompts |
| Authorization | Actor lacks permission | Stop and obtain the correct access or reviewer decision |
| Capability | Operation or modality is unsupported | Select a compatible tool, model, or workflow |
| Validation | Inputs do not match the contract | Correct the request using the owning schema |
| Runtime | Call times out or target rejects the action | Preserve the error and check retry guidance before repeating |
| Verification | Product reports success but target evidence is absent | Keep the outcome unresolved until the target confirms it |
Automatic retry behavior is not established in this batch. Repeating a state-changing call can create duplicate effects, so a retry should be explicit and evidence-driven.
The safe default for an unverified integration is read or propose. Move to execution only after the tool contract, credential scope, permission, approval, and verification path are all grounded.
A reliable integration guide must distinguish unavailable credentials, unsupported capability, provider failure, invalid input, denied action, and incomplete execution.
The current evidence verifies several model-catalog statuses, not a universal integration error model. Preserve the visible error and status, avoid unsafe repeated retries, and use the owning product’s troubleshooting guidance.
Before enabling a state-changing tool
Use a preflight review before any tool can create, modify, send, delete, or publish:
- Verify the exact tool and integration contract.
- Confirm the target system and object.
- Validate inputs without exposing credentials.
- Establish the current actor’s permission.
- Define which changes require approval.
- Determine whether the operation is idempotent or can create duplicate effects.
- Identify the receipt, log, response, or target evidence that proves completion.
- Define a stop condition for partial or ambiguous outcomes.
Batch 01 does not prove that Ethen supplies these controls uniformly. The list is a requirement for the later product guide, not a claim about current UI.
Read-only does not mean consequence-free
A read operation can still expose sensitive information, consume provider resources, or influence a later proposal. Verify which fields the integration returns, whether the agent needs all of them, and how the output enters workspace context. Avoid copying complete external records when a narrower summary or identifier would support the task.
If a read result is transformed by a model, keep the original source or a traceable reference. The generated summary should not become the only evidence of external state.
Partial completion
An integration may complete one stage and fail at another. A request can authenticate, pass validation, reach the target, and still fail to create the intended result. Report the furthest confirmed stage rather than using a binary success label.
For example, “request accepted by the tool” is weaker than “target system confirmed the change.” If the target response is unavailable, leave verification unresolved. This wording protects reviewers from treating an intermediate acknowledgement as proof of completion.
Recovery decisions
Recovery should depend on failure class. Correct invalid input before retrying. Resolve a missing credential through the supported configuration path. Obtain permission rather than bypassing a denial. Choose a different capability when the modality is unsupported. For an ambiguous state-changing result, inspect the target before sending the same operation again.
Preserve the original error and the recovery decision in the task evidence. A repaired integration is easier to trust when the history shows why the next attempt was safe.