Design an Agent Tool
A Tool is a curated agent-facing capability. It must be easy to select correctly, strictly validated, and bounded enough that a model cannot broaden its authority by manipulating arguments.
When to introduce a Tool
An endpoint, node, or reusable function never automatically implies a Tool.
- the representative Agent task is identified;
- the required authority is legitimate and declarable;
- the intent is distinct from neighboring Tools;
- the granularity reduces plumbing without hiding a workflow;
- the value can be evaluated on complete tasks.
Avoid universal Tools such as manage_resource that arbitrarily combine object type, operation, and fields. Reducing the number of Tools is not a goal if it increases ambiguity.
Who controls the parameters?
Every declared parameter must explicitly belong to a controller:
| Control | Use | Examples |
|---|---|---|
model | A genuine business choice delegated to the model and validated by the Tool. | Email subject, bounded search criteria, business reason. |
designer | A value chosen or locked by the designer, not modifiable by the model. | Extension configuration, sending account, governed resource. |
Trusted runtime context — merchant, credentials, execution identity, authority snapshot — must not be added as a pseudo-parameter that can be controlled. It is supplied outside the Tool's argument surface.
A provider configuration is designer-only by default: it selects credentials, provider identity, and disclosure boundary.
Observations and completeness
- choose outputs for the Agent's next decision, not to mirror a complete provider payload;
- never call a partial projection
platform.*; - bound the number of results, depth, text, and search range;
- explicitly signal a partial response and its continuation mechanism;
- preserve classification and provenance when summarizing, joining, or flattening.
An empty result, a missing optional field, an unavailable section, and a failure are four different situations. The contract must distinguish them.
Mutations and repetition
Prefer one identifiable business commitment per mutating Tool. Do not hide several independent effects behind one “convenient” call unless the composite operation has a genuine business contract.
An Agent may call a Tool again. Idempotency must come from the canonical service, an operation identity, or the partner protocol; do not simulate exactly-once by storing only a hash of the arguments.
After a transport error on a mutation, state may be uncertain. Provide a read/reconciliation path rather than recommending a blind retry.
Catalog lifecycle
Tools provided by an extension use <extension_key>.<snake_case> and the prefix exactly matches metadata.name from the manifest. An extension cannot take the reserved identity ormuz, which is used by platform Core executables. A Tool may share underlying behavior with a node without depending on its identity or being created automatically by symmetry.
Changing arguments, outputs, effects, or risk_level is a contract change. Existing activities must not be silently retargeted to a broader capability.