Agent capabilities and tools

Agent capability is not a single on/off setting. It emerges from the registered agent, the selected tool contract, execution state, workspace scope, permission mode, risk classification, credentials, and approval requirement.

Tool definitions include planned and contract-only entries; those states must not be described as live execution.

Tool governance is multidimensional. Execution state answers whether implementation exists; permission mode limits authority; risk describes potential impact; approval requirement determines whether a human decision is needed; provider and scope identify where the operation can run. Evaluating only one field is unsafe. An available tool can still be blocked for a particular agent, workspace, credential state, or approval policy, while a planned tool should never be described as runnable regardless of its name or category.

Capabilities

Availability should be re-evaluated for each environment.

An agent capability is the intersection of its definition, active implementation, eligible tools, workspace scope, credentials, policy, and approval state. Registry publication alone does not grant execution. A capability can remain descriptive when its implementation is a stub or when its tools are contract-only or planned.

Functional-agent contracts may declare workflow steps, evidence, artifacts, proposed actions, approval boundaries, fixtures, and evaluation cases. Each declaration should be read as a requirement unless the runtime and connected tool path are also active.

An agent can only use capabilities represented by its configuration and permitted runtime contracts.

Allowed agents and workspace archetypes can narrow a tool definition.

Registry implementation status still determines whether the agent itself can create a run.

Capabilities describe what the agent contract is intended to do; tool definitions describe how a specific operation is bounded. Neither should be read as proof that a run completed successfully.

The tool governance contract includes the fact that risk levels range from read-only through write, user-content writes, external side effects, destructive, and privileged. Execution states are available, contract-only, and planned. A planned or contract-only tool is not executable even when its identifier and schema are fully declared.

An action’s risk and policy result can deny execution, create an approval proposal, or permit a start. High-risk or approval-required actions should produce a proposal before any execution authority is assumed.

Tool contracts

Input and output summaries should be specific enough for reviewers to understand the operation without becoming a substitute for a typed runtime schema. When the exact schema is not supplied, keep examples conceptual and retain the grounding flag.

A tool definition can include category, risk, read-only status, approval requirement, execution state, provider, allowed agents, allowed workspace archetypes, and input and output summaries. These fields describe who may call the tool, under what conditions, and what kind of effect it can have.

Execution state is decisive: available represents a current path, contract_only exposes a contract without execution, and planned records future intent. Do not convert the ToolId union into a live support matrix.

Execution states are available, contract_only, and planned.

The contract describes boundaries but does not itself prove credentials or a working external integration.

A tool contract identifies category, risk, read-only behavior, approval requirement, execution state, provider, allowed agents and workspaces, and summarized input and output. Those fields should agree before the runtime attempts an action.

Permission modes are plan-only, read-only, safe-edit, and full-access. Tool output should remain tied to its action and evidence records rather than being treated as an unqualified final result.

Risk levels range from read-only through write, user-content writes, external side effects, destructive, and privileged. Do not infer connector support, retry behavior, or provider-specific contracts beyond the supplied tool definitions.

Approval requirements are no approval, confirm once, confirm every time, and blocked. Execution state, permission mode, risk, approval requirement, provider, and scope answer different questions about a tool.

Permissions

Approval is determined before a side-effecting action starts. The tool contract contributes its risk and approval requirement; agent and workspace policy can narrow that authority further. A proposed action should carry enough parameters and evidence for a reviewer to understand the change. Approval permits the specific governed action—it does not broadly activate the tool for unrelated runs or scopes.

Permission review should consider the output as well as the requested operation. A read action can return sensitive context, while a safe edit can still affect user content. The permission mode, risk level, approval rule, and output summary should be evaluated together rather than ranked on one scale.

Permission modes are plan_only, read_only, safe_edit, and full_access. Risk levels include read_only, write, writes_user_content, external_side_effect, destructive, and privileged. Approval requirements are no_approval, confirm_once, confirm_every_time, and blocked.

These axes are independent. A tool can have an available implementation but remain blocked by policy. A safe-edit permission does not cancel a confirm-every-time requirement. A read-only tool can still be unavailable because its provider or connector is not active.

A permission mode limits what an agent may attempt, while risk and approval controls still apply to each action.

Do not use full_access as a substitute for explicit tool eligibility.

Permission modes set the maximum authority available to the tool. Plan-only and read-only are materially different from safe-edit and full-access, and the selected mode does not remove an independent approval requirement.

A tool definition can name its provider, allowed agents, allowed workspace archetypes, input summary, and output summary.

Permission mode answers what kind of operation the agent may request; risk level describes the consequence if that operation executes. plan_only should not be interpreted as read access, and full_access does not erase a tool’s approval requirement or project policy. Evaluate all three dimensions together before allowing an action to start.

Allowed-agent and workspace-archetype fields can narrow use further. A tool that is otherwise available should still be denied when the current agent or workspace falls outside those declarations.

Credential use

Tool credentials should be resolved through the supported provider or integration path and scoped to the permitted agent and workspace. The type contract can name a provider, but it does not prove that credentials are configured or that every provider is live.

Do not place secrets in instructions, ordinary run input, evidence, screenshots, or tool-output summaries. When a credential is missing, keep the failure separate from tool risk, approval, and implementation state.

A tool or connector can require credentials that are not represented in the generic type definition.

Secrets should be resolved by the execution environment rather than placed in run inputs or instructions.

Missing credentials should stop or gate the action rather than be treated as model reasoning failure.

Credentials belong to their provider or connector secret path. They should not be copied into run inputs, action summaries, evidence, or support messages merely because the tool needs them.

Failure behavior

Different failures require different recovery. A scope denial is corrected through agent or workspace configuration. A missing provider credential is corrected through the integration’s credential path. A blocked approval requirement needs a policy or contract decision, not a repeated tool call. A tool execution error belongs to the action record and may require inspection of partial side effects before any retry.

Planned and contract-only tools should return an honest unavailable result rather than simulated success. Demo fixtures may illustrate output shape, but the resulting record must remain labeled as fixture or mock evidence.

The helper layer can block an action, request approval, or start it. A blocked result indicates that the action cannot proceed under current policy or contract. An approval-required result creates a proposal context. A tool error after execution begins should be recorded on the action and reflected in the run’s allowed transition path.

Do not assume a generic retry policy for all tools. External side effects, destructive operations, and user-content writes can be unsafe to repeat without understanding whether the first attempt partially succeeded.

Tool decisions can be allow, ask, or deny.

Approval requirements can be no_approval, confirm_once, confirm_every_time, or blocked.

Helpers can mark an action blocked, create a proposal, await approval, start execution, or reject the run after a denied decision.

Failure can mean unavailable implementation, blocked policy, missing approval, invalid scope, missing credential, adapter error, or an invalid run transition. Preserve the action and decision records so those cases are not collapsed into one tool error.

Resolve execution state and scope first, then grant the least powerful permission mode that can complete the intended action.

A blocked decision is not an execution error: policy has intentionally prevented the action. An ask result creates an approval boundary, while an unavailable or contract-only tool indicates that no live execution path should begin. Keep these outcomes distinct in action status and operator messaging so a user does not retry a denied request as though it were a transient tool outage.

Best practices

Recheck tool status after deployments or configuration changes; an earlier available state is not a permanent guarantee.

Choose the least powerful permission that can complete the task, require approval at the risk level defined by the contract, and expose only tools whose execution state is available. Review provider and workspace restrictions before a run starts.

Keep the action record complete enough to show tool ID, ordered step, risk, status, proposal, input summary, output, and timestamps. That record supports review without treating the tool’s returned text as trusted authority.

Prefer the least-permissive permission mode that completes the task.

Keep destructive, privileged, external-side-effect, and user-content writes visible in proposals and evidence.

Verify execution state and scope each time a tool contract or agent registry entry changes.

Use the least powerful executable tool contract that satisfies the task, keep side effects reviewable, and require explicit evidence before increasing permission or reducing approval frequency.

The ToolId union includes planned and contract-only entries; a contract, provider field, or category does not by itself prove live execution.

Choose tools by execution state before considering convenience. available indicates an implemented path in the inspected environment; contract_only describes a declared interface without a live execution guarantee; planned is future intent. Permission mode limits the kind of work an agent may request, risk level describes the potential effect, and the approval requirement determines whether the helper can proceed, must ask, or must block.

A tool marked read-only can still return untrusted or sensitive data, while a write-capable tool may require confirmation once or every time. Provider, allowed-agent, workspace-archetype, input-summary, and output-summary fields further narrow the contract. Credentials should be resolved by the integration path and must not be copied into run inputs, evidence, or support records. A failure should retain the tool ID, action status, risk, proposal relationship, and redacted error so operators can tell a denied action from an unavailable implementation.