{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://humanoidindex.io/standard/schema/tool-definition.schema.json",
  "title": "HIS Layer 3 Tool Definition",
  "description": "One entry in a tool server's tools/list response — the shape an LLM orchestrator reads to decide what it can call and how. Modeled directly on MCP's tool-definition shape, plus a risk_tier for the mandatory physical-safety gating a robot control protocol needs that a generic tool protocol doesn't.",
  "type": "object",
  "required": ["name", "tier", "risk_tier", "description", "input_schema"],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$",
      "description": "Stable tool identifier, e.g. 'grasp', 'navigate_to'."
    },
    "tier": {
      "type": "integer",
      "enum": [0, 1, 2],
      "description": "0 = raw actuator/joint-level (expert only, not meant for cross-vendor LLM orchestration). 1 = skills — the interoperable layer an orchestrating LLM should target. 2 = semantic tasks composed from tier 1, often vendor-specific and not guaranteed portable."
    },
    "risk_tier": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "description": "0 = no physical effect (e.g. 'speak', read-only queries). 1 = physical motion in a controlled/expected envelope (e.g. locomotion in open space). 2 = physical motion with contact/manipulation risk (e.g. grasp, hand_off). 3 = physical motion with elevated human-proximity or force risk. A call is gated per the robot's manifest.interfaces.safety.confirmation_required_above_tier (see robot-manifest.schema.json) — this is what makes that field meaningful rather than decorative."
    },
    "description": {
      "type": "string",
      "description": "Human- and LLM-readable explanation of what this tool does and when to use it."
    },
    "input_schema": {
      "type": "object",
      "description": "JSON Schema for this tool's call arguments."
    },
    "output_schema": {
      "type": ["object", "null"],
      "description": "JSON Schema for this tool's result payload, if declared."
    }
  }
}