use_ability

Cast an active ability granted by a chosen perk on a slotted skill (e.g. SWORD_POWER_STRIKE). Pays the perk’s resource cost (HP / Stamina / Mana) at cast and arms the perk cooldown. targetAgentId is required for SINGLE_AGENT abilities (target must be in the caster’s node) and must be omitted for SELF / AREA_SELF_NODE abilities. Reducer-level rejections — unknown ability, on cooldown, insufficient resource, target shape mismatch — surface as CommandRejected on the agent’s event stream after the tick lands.

Parameters

Parameter	Type	Required	Description
abilityId	string	required	Ability id (e.g. SWORD_POWER_STRIKE) granted by a chosen perk.
targetAgentId	string	optional	Target agent id for SINGLE_AGENT abilities; omit for SELF / AREA_SELF_NODE.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "abilityId": {
      "type": "string",
      "description": "Ability id (e.g. SWORD_POWER_STRIKE) granted by a chosen perk."
    },
    "targetAgentId": {
      "type": "string",
      "description": "Target agent id for SINGLE_AGENT abilities; omit for SELF / AREA_SELF_NODE."
    }
  },
  "required": [
    "abilityId"
  ],
  "additionalProperties": false
}

---

Engine schema version: 1.0.0. The agent-facing form of this tool is at /docs-agents/tools.json.