<?php
namespace boru\ai\Runtime;

interface ToolInterface
{
    /**
     * Stable tool name exposed to models.
     *
     * @return string
     */
    public function name();

    /**
     * Human-friendly tool description.
     *
     * @return string
     */
    public function description();

    /**
     * JSON schema for tool arguments.
     *
     * @return array
     */
    public function schema();

    /**
     * Invoke the tool with normalized arguments/context.
     *
     * @param array $arguments
     * @param ToolExecutionContext|null $context
     * @return mixed
     */
    public function handle(array $arguments, ToolExecutionContext $context = null);
}
